Floatbox v8.5 - Options Reference

For the current version 8.5.
For other versions, see the docs in the downloaded package.

Floatbox provides versatility in how it can be configured and used through numerous configuration options and a variety of ways and locations to set those options. This document gives information about the configuration options. See the instructions for information on how these options can be configured globally, with page-specific settings, assigned to only small-screened mobile devices, and targeted to specific classes, content types or individual items.

Index (and quick-reference)


shadowType - 'drop' | 'hybrid' | 'halo' | 'none'
Set 3D shadow effect. 'drop' sets a 2-sided shadow on the right and bottom. 'hybrid' sets the full shadow on the right and bottom and a fainter half shadow on the left and top. 'halo' sets a full shadow on all 4 sides.

shadowSize - pixels (10)
Sets the width in pixels of the shadow effect around the box.

shadowOpacity - 0-1 (0.4)
The opacity or darkness of the shadow effect around the box.

outerBorder - pixels (1)
Width of the border around the outside edge of the box.

innerBorder - pixels (1)
Width of the inside border around the edge of the main content.

outerBorderRadius - pixels (10)
This sets the border-radius for the outer box perimeter, in pixels.

innerBorderRadius - pixels (0)
Set the border-radius for the inner content area,in pixels.

padding - pixels (20)
Width of the area between the floatbox content and the outer floatbox edges.

panelPadding - pixels (6)
Gap above and below the contents of the floatbox frame area like the caption and close buttons. Provides the vertical spacing between the floatbox outer edge, frame content, and main content.

headerGap - pixels (0)
footerGap - pixels (0)
Gap between the header and footer elements and the main floatbox outer edges.

overlayOpacity - 0-1 (0.55)
Opacity or darkness of the full-screen page overlay. 0 is fully transparent, 1 is fully opaque.

Back to Index


doAnimations - true | false
Setting doAnimations to false is a short-hand way of setting transitionTime, resizeTime and overlayFadeTime all to 0. When doAnimations is false, startAt, endAt, zoomSource, imageTransition and splitResize become irrelevant.
(To turn off animations only on smallScreen devices (phones), put "doAnimations:false" in a 'mobile' options set.)

overlayFadeTime - seconds (0.4)
Number of seconds for the opacity fade-in and fade-out of the translucent overlay which covers the host page.

resizeTime - seconds (0.7)
Controls the speed of the animated opening and closing resize of the floatbox from and to the thumbnail or click starting position.

fadeTime - seconds (0.4)
This is the time taken to fade in the box contents immediately after starting up the floatbox or before closing it down. If not overridden, tooltips will use 0.2 seconds for fadeIn and context boxes will use 0.

transitionTime - seconds (0.8)
Controls the speed at which transitions between gallery set images occur.

imageTransition - 'crossfade' | 'slide' | 'shift' | 'expand' | 'fade' | 'none'
A variety of animations are available when transitioning between two images in a gallery set. These transitions will be synchronized with any floatbox resizing that needs to occur such that all animations will complete simultaneously. The default transition setting is 'crossfade', which fades out the old image while fading in the new one. 'slide' does not alter opacity but instead will slide the current image out of the floatbox and thereby reveal the stationary next image underneath it. Regardless of the imageTransition setting, if a touch user uses a swipe gesture to navigate through an image gallery, the 'slide' effect will be done, because it looks very natural when swiping. The 'shift' setting is similar to 'slide' except that instead of being stationary, the new image will slide into the box while the current image slides out, as if the two images were attached at their edges. 'expand' is kind of like an accordion seam; it's a little hard to explain - try it to see it. A setting of 'fade' will cause the images to fade to black (or whatever the current colorTheme is), resize the box if necessary, and then fade the new image in from black. 'imageTransition:none' is equivalent to setting transitionTime:0, and is not recommended because it makes things look jumpy and jarring.

startAt - id | 'start' | null
endAt - id | 'start' | null
The default starting and ending point for box opening and closing animations is at a thumbnail for zoomSource starts, or at the starting click/touch screen location, or from the center of the screen. Set startAt and/or endAt to the id of an element on the document to animate from the center point of that element. Set them to null to animate to/from the screen center. And, somewhat obscurely, set them both to 'start' to make zooming up/down from a thumb start/end at the thumb's center point rather than from the thumb element's displayed size. This is helpful when the zoomSource image does not match the thumbnail image.

zoomSource - img filePath | null
Default behaviour for images and video is to do 'zoom' animations up from and down to the clicked anchor when opening and closing. The image zoomed is the same image that is being shown. The zoomSource option can be used to assign an alternate image to use for the zoom animation. Set zoomSource to the path of an image file to be used in the animation.
Any content type can have a zoomSource image assigned to it, so for example, a form can open by zooming up a screen capture image of that form. To disable the image zooming effect, set zoomSource to null. Note: To zoom from the center point of a thumb instead of its full size, set 'startAt' and 'endAt' to 'start'.

splitResize - true | false
Default animated resizing of floatbox resizes width, height, top and left simultaneously. Setting splitResize to true yields sequenced animation where the X and Y dimensions are resized seperately. When split-resizing, the smallest dimension will be sized first, followed by the other larger dimension. This avoids unaesthetic resize behaviour of initially bloating up in the larger dimension. Note that splitResize does not take effect while 'zooming' an image in or out or while cross-fading between images in a gallery set.

easing ** - 1-4 (2.5)
Floatbox size and position animations are normally 'eased', meaning they are slower at the start, faster in the middle, slower at the end. The 'easing' option modifies the strength of the acceleration curve, with a value of 1 flattening the curve to linear, thereby turning off easing.

inflection ** - 0-1 (0.5)
The 'inflection' option sets the transition point where easing switches from deceleration to acceleration. The default of 0.5 puts it right in the middle of the animation. Decrease the inflection point to move the transition point closer to the start of the animation and increase it to move closer to the end.

animationTime ** - seconds (1)
This sets the default speed of animations done by the fb.animate API function that haven't specified a speed in their call parameters.

Back to Index


colorTheme - 'black' | 'blue' | 'silver' | 'white' | 'yellow' | 'red'
When the colorTheme option is not specified, floatbox defaults to black for images, silver for HTML content, and blue for multi-media. Assigning a specific colorTheme setting overrides these defaults.

boxColor - css color [|css color]
'boxColor' assigns the main background color of the floatbox's frame area using any css color. A gradient effect can also be assigned to the floatbox by setting boxColor to two css colors separated the the '|' character.
If defining a gradient, hex color formats must be used. For example: boxColor:#123456|#edca98
If a gradient is set, outerBorderRadius is set to 0 and the floatbox will have square corners. Note that setting boxBackgroundImage can override a boxColor assignment.

overlayColor - css color
innerBorderColor - ...
outerBorderColor - ...
Assign any standard css color to various floatbox components using these options. A good way to do extensive appearance customizations is to set the desired options in a className definition fbOptions.js (or in fbOptions on a page). Once this is done, the collection of option settings can be assigned to one or more floatboxed links simply by placing the assigned class name on them.

textColor - css color
strongTextColor - ...
These work the same as the other color options. 'textColor' applies to the 'item x of y' display, index links, and the 'open in a new window' link. 'strongTextColor' applies to captions, info and print links, and the new window link when it's hovered.

contentBackgroundColor - css color
The default background color of floatbox's content area is white for non-iframe HTML content and transparent for all others. If a different background color is required for some content, the desired color can be assigned by setting the 'contentBackgroundColor' option. Valid values are any color values that can be assigned via css. This setting will have a visible effect ony if the content shown has some transparent areas.

boxBackgroundImage - img filePath
The main floatbox frame area can have a background image assigned to it to give texture or other effects. Set 'boxBackgroundImage' to the URL path of the image to be used as the background.

overlayBackgroundImage - img filePath
A repeating background image can be assigned to the normally translucent page overlay. Set 'overlayBackgroundImage' to the URL path of the image to be used as the background, and perhaps also set "overlayOpacity:1" to make it opaque.

Back to Index


autoFit - true | false
Default behaviour for content that is larger than the viewable screen is to auto-size the floatbox such that it fits within the screen. Set autoFit to false to disable this auto-sizing and allow the displayed floatbox to be larger than the visible screen.

autoFitSpace - pixels (5)
The minimum space to leave between the floatbox edge and the browser window edge when autoFitting content.

enableImageResize - true | false
If enableImageResize is set to true, images that have been autoSized to fit the screen, that have been resized with drag-resizing, or are displayed larger than the current screen size can be resized using the resize tool.

inFrameResize - true | false
An image may be displayed at smaller than its native size when autoFit causes it to scale to fit the viewport. The image can then be resized to its full size using the resizeTool as described below. The default resizing behaviour is for the floatbox frame to remain at its smaller size inside the viewport and for the image to scale up to its full size inside the floatbox frame. It can then be panned within the frame by mouse or touch drags on the enlarged image or mouse moves over the image (see 'hoverPan' below). Set inFrameResize to false to disable this behaviour and cause the entire floatbox, including the frame, to to scale up to full size when requested.

hoverPan - true | false
An image that has been in-frame-resized to larger than the containing floatbox content area will, by default, move and pan within the content area in response to mouse moves over the content. Set hoverPan to false to disable mouse-move panning.

resizeTool - 'cursor' | 'topleft' | 'both'
Sets the tool used when enableImageResize is true. The cursor tool enables clicking on the image to resize and displays a magnifying glass as the mouse cursor to show when resizing is allowed. The topleft tool is a small semi-transparent button in the top left corner of the image. Default behaviour when resizeTool is not specified is for mouse users to get the 'cursor' and touch users to get the 'topleft' tool.

enableDragResize - true | false
If true, a small resize widget will be shown in the bottom right corner that mousers can drag on with their mice to resize the box. Not available when using touch gestures.

draggerLocation - 'frame' | 'content'
If enableDragResize is true, and image content is being shown, and draggerLocation is set to 'content', the resizer widget will be placed at the bottom right corner of the content area instead of in the frame area.

stickyResize - true | false
'stickyResize' causes size changes made to a floatbox by 'dragResizing' to persist in subsequent box size calculations. Set it to false to have the floatbox return to normal size when showing the next item in a set.

minWidth (140) - pixels | 'xx%'
minHeight (100) - ...
minWidth and minHeight set the lower limits for the dimensions of the displayed content, not including the floatbox frame outside of the content. The content will be displayed at at least these dimensions and cannot be drag-resized or auto-sized smaller than these limits. minWidth and minHeight can be set as a number of pixels or as a percentage of the visible screen size.

maxWidth (0) - pixels | 'xx%'
maxHeight (0) - ...
maxWidth and maxHeight set the upper size limits for floatbox content dimensions. When set to 0, no limit is in effect and the content will be presented at its native, specified or measured size.
If these options are applied to image content and are smaller than the image's native dimensions, the image will still be resize-able up to native dimensions (provided the enableImageResize option has not been set to false).
maxWidth and maxHeight can be set as a number of pixels or as a percentage of the visible screen size.

minBoxWidth (0) - pixels | 'xx%'
minBoxHeight (0) - ...
minBoxWidth and minBoxHeight can be used to setup a floatbox frame area larger than it would normally be based on the padding option and content size. In a gallery set or slideshow, this could be used to define a floatbox that fills the screen and remains a constant size while the content area inside the box changes to accommodate the various gallery set members.

Back to Index


boxLeft - pixels | 'click' | 'xx%'
boxTop - ...
Default box positioning is for the floatbox to open centered in the viewable browser screen area (with a little offset toward the top). The 'boxLeft' and 'boxTop' options can be used to change this default box placement. If set to simple integers, those integers will be taken as screen pixel locations at which to place the floatbox. These pixel placement values are relative to the visible browser viewport and not to the underlying document. If set to the string 'click', the floatbox's left and/or top edge will open at the mouse click or touch location. The 'boxLeft' and 'boxTop' positions can also be set as a percentage of the screen size. For example, a 'boxLeft' setting of '50%' will place the left edge of the floatbox at the screen centre.

boxX - pixels | 'click' | 'xx%'
boxY - ...
Similar to boxLeft and boxTop, except boxX and boxY positions the center point of the floatbox instead of the top-left corner. For example, 'boxX' and 'boxY' both set to '50%' will exactly center the floatbox on the screen, provided it fits entirely within the screen. If both 'boxX' and 'boxLeft' are set, 'boxX' wins and 'boxLeft' is ignored. Similarly for 'boxY' and 'boxTop'.

boxLeftAdjust - pixels | 'xx%'
boxTopAdjust - ...
boxLeftAdjust and boxTopAdjust are added in to the floatbox positioning after all other position calculations such as autoFit and default centering are complete. Specified as + or - pixel count or percentage of screen size, they move the final floatbox position the requested amount. These adjustments are most typically used to alter the placement of enhanced tooltips and context boxes.

captionPos ('bl') - 'tl' | 'tc' | 'tr' | 'bl' | 'bc' | 'br'
caption2Pos ('tc') - ...
infoLinkPos ('bl') - ...
printLinkPos ('bl') - ...
newWindowLinkPos ('tr') - ...
itemNumberPos ('bl') - ...
indexPos ('br') - ...
controlsPos ('br') - ...
These options control the positioning of the various widgets that can appear in the floatbox border area. See the 'layout' section of the instructions for more detail if required. Values are short-hand for top-left, top-center, top-right, bottom-left, bottom-center and bottom-right.

outerClosePos - 'tl' | 'tr'
The round outerClose button, when enabled with 'showOuterClose', defaults to being place on the top-right corner of the floatbox. It can instead be placed on top-left corner by setting outerClosePose to 'tl'.

detachOuterClose - true | false
The outerClose button normally is attached to one of the top corners of a floatbox. Setting detachOuterClose to true will remove the button from the box and pin it to one of the top corners of the screen or viewport.

strictCentering - true | false | 'top' | 'bottom'
strictCentering defaults to true and ensures that any captions or widgets positioned in the 'tc' or 'bc' positions will be accurately centered in the floatbox frame area. This can be expensive in terms of leaving blank space on either side of the centered components, especially on small screens, and so strictCentering is set to false for mobile devices in fbOptions.js. Set strictCentering to 'top' or 'bottom' to limit the centering to that panel area only, or set it to false to disable it for both panels.

centerNav - true | false
When the navigation controls (set by controlsPos) are in one of the corner positions ('tl', 'tr', 'bl', 'br'), the "← prev next →" controls can be moved to the center of the corresponding panel by setting centerNav to true.

enableDragMove - true | false
If 'enableDragMove' is not set to false, a floatbox can be dragged around the screen by a touch-move gesture or a hold-down of the left mouse button on the floatbox frame outside of the main content area.
The box can also be dragged around from image content, unless it is a multi-image gallery set and touch gestures are being used. (Touch-swiping a gallery set image is reserved for navigation to the previous or next image in the set.)
fbTooltip and fbContext boxes cannot be moved by user input.

stickyMove - true | false
'stickyMove' causes position changes made to a floatbox by dragging the floatbox around the screen to persist in subsequent box position calculations. Set it to false to have the moved floatbox return to centered position when showing the next item in a set.

Back to Index


showControlsText - true | false
If set to true, the text on the various controls will show for all browsers, and if set to none, no browsers will get text on the controls. The default is for smallScreen devices to not get the text, but everybody else does.

showClose - true | false
Enables/disables display of the close button in the floatbox border area.

showOuterClose - true | false
Enables/disables display of the round external close button that can be shown at one of the top corners of a floatbox.

showPrint - true | false
If showPrint is set to true, a "Print..." link will be shown in the floatbox border area. This print link invokes a print dialog that will print just the floatbox contents, not the underlying page. (The "Print..." text is translated/regionalized in the language files.) See the printCSS option for how to pass css stylings to the print content. Print links will not be shown for cross-domain iframe content because cross-domain script blocking will prevent the printing from succeeding.

printCSS - css text | css filePath
When showPrint is enabled, it may be necessary to provide some css to format the print content. The desired CSS settings can be provided directly as text. For example, printCSS:`h4 {color: #123456;} a img {border: 2px solid black;}`. 'printCSS' can also be set to the path of an external css file which will be attached and applied to the print window contents. E.g., printCSS:myPrint.css.

printText - string
Replaces the default text "Print..." (or the translated equivalent) used for the print link with text of your choice.

infoOptions - option string
Used in conjunction with the 'info' option, this allows assigning configuration options to the secondary info floatbox using the standard options attribute syntax. Wrap the infoOptions in backquotes for correct parsing and see the instructions and demo for more details.

infoText - string
Replaces the default text "Info..." (or the translated equivalent) used for the info link with text of your choice. For example, if displaying EXIF information through the info option, the 'infoText' options could be set to "EXIF..."

showNewWindow - true | false
If showNewWindow is set to true, a "Open in a new window" link will be shown in the floatbox border area. Clicking this link will open a new browser window or tab with the floatbox content loaded as an ordinary page. ("Open in a new window" is translated/regionalized in the language files.) Use the closeOnNewWindow option in conjunction with showNewWindow.

closeOnNewWindow - true | false
When set to true, floatbox will end (close) when the newWindow link (described in the options reference and instructions) is clicked.

showHints - 'once' | true | false
Controls display of system tooltip messages on mouseover of the nav and control buttons. These tooltip messages are intended to be used to inform users about keyboard navigation shortcuts. With the default setting of 'once', each tooltip will deactivate after it has been displayed for sufficient time to be read. A tooltip message will also be deactivated if the user navigates with the associated keyboard shortcut. If enableKeyboardNav is set to false, showHints will be set to false.

outsideClickCloses - true | false
Default behaviour when outsideClickCloses is not set is for modal boxes, tooltips and context boxes to close when something outside the floatbox is clicked or touched. Set this to true to make non-modal boxes close on an outside click, or false to make any box ignore outside clicks.

contentClickCloses - true | false
If set to true, floatbox will exit when the user clicks on the floatbox's displayed content. This option is primarily useful for images and context boxes. By default, a context box will close when the page outside of the floatbox is click or touched, but remains open if interaction occurs within its content. When set for images that have the navigation overlay active (navType = 'overlay' or 'both'), the click-to-close area is down the center of the image in the space remaining between the left and right navigation areas.

enableKeyboardNav - true | false
Enables or disables the keyboard handler for previous/next, pause/play, resize and close actions.

Back to Index


navType - 'overlay' | 'button' | 'both' | 'none'
Sets the type of navigation controls to display. 'overlay' is the "Prev/Next" image overlay.' 'button' gives "<<prev||next>>" in the controls area of the floatbox frame. Overlay navigation is not available for html and multi-media content, just for images.

navOverlayWidth - 0-50 (30)
Sets the width in percentage of each of the left and right transparent overlay nav panels that provide navigation through mouse clicks on the displayed image. If set to 50, each panel will be half the image width and so will meet without a gap in the middle. 40 leaves a 20% gap between panels, etc. If enableImageResize or contentClickCloses are active, a gap should be left between the nav panels so that there's somewhere on the image that can be clicked.

navOverlayPos - 0-100 (33)
When the mouse is active over an image with navType 'overlay' or 'both' set, small prev/next graphics are displayed. This setting is the percentage height from the image top that the top edges of these graphics will appear. 0 puts them right at the top, and 100 places them at the bottom of the image.

showNavOverlay - true | false
This option does not enable or disable the overlay navigation - use navType for that. 'showNavOverlay' controls the visibility of the overlayed navigation 'prev' and 'next' graphics.
Set "showNavOverlay:true" to force it always on, and "showNavOverlay:false" to turn it always off. When the overlay nav graphics are turned off, overlay nav still works; it's just not displayed. The default when showNavOverlay is not set is for Floatbox to make an intelligent choice based on content type and touch vs. mouse usage. When both the overlay and button nav types are enabled, the button nav controls will highlight as the mouse moves over active image areas, regardless of the 'showNavOverlay' setting.

enableSwipeNav - true | false
Setting enableSwipeNav to false turns off the ability for touch users to navigate through a gallery set with swipe gestures on the images.

showItemNumber - true | false
Setting showItemNumber to false will disable the display of the 'image/page x of y' text in gallery sets.

enableWrap - true | false
Enables gallery wrapping so that selecting 'next' on the last item wraps to the first, and selecting 'prev' on the first item wraps to the last. Because gallery viewing can start anywhere in a series of images, it is probably a good idea to leave this set to true in most circumstances. However, if displaying something like a series of instructions that always starts with item #1, it may be appropriate to turn wrapping off. The enableWrap option affects only mouse and keyboard navigation. Even when enableWrap is set to false, a slideshow will wrap if started with an item other than #1 or if the afterSlideshow option is set to 'loop'.

numIndexLinks - number (0)
Index links are a grouping of numbered links that will jump floatbox to the selected item of a gallery set when clicked. They look like this: "1 2 3 4 5 ..."
If set to 0, no index links will be shown. If set to -1 or to a number greater than the number of items in a gallery set, all index links will be shown - one for each item in the gallery. If set to a positive integer less than the number of gallery items, only that number of links will be shown. For example, if maxIndexLinks = 9 for a 99 item gallery, the index links will look something like "1 ... 12 13 14 15 16 17 18 ... 99"

showIndexThumbs - true | false
Controls the display of popup thumbnails in the indexLinks group. If true, thumbnail popups will be displayed when an index link is hovered.

maxIndexThumbSize - pixels (0)
The popup thumbnails used in the index links are taken from the img elements inside the associated anchor on the base page. These thumbnails may be larger than desired for the index links popup thumbnails. The index link thumbnail sizes can be limited by setting maxIndexThumbSize to the desired pixel size of the thumbnail's largest dimension. If maxIndexThumbSize is 0, the index link thumbnails will be shown at their native size.

indexThumbSource - img filePath | 'href'
When showIndexThumbs is true, the default index thumb source is the thumbnail image from a gallery item's associated anchor (link) element on the main page. If there is no such thumbnail, or if an alternate thumbnail is desired, the path to the desired thumbnail image can be specified in the indexThumbSource option. If indexThumbSource is assigned the value 'href', the main image linked to by the host anchor's href attribute will be used as the index thumb. When using the 'href' setting, the maxIndexThumbSize option should be set as well.

randomOrder - true | false
Gallery sets of multiple items normally are ordered by their position in the html document. Setting randomOrder to true causes a gallery set to sequence its member items in a random order. This can be a nice touch for some slideshows.

Back to Index


doSlideshow - true | false
If set to true, images in a gallery set will be launched as a slideshow.

slideInterval - seconds (4.5)
This is the number of seconds to display each image in a slideshow before moving on to the next one. Per-item intervals can be assigned to the item options of individual slideshow members.

afterSlideshow - 'exit' | 'stop' | 'loop'
Describes what to do when all images in a slideshow have been seen. Note that if a slideshow was started on other than the 1st image, it will wrap around until all images have been seen before acting on the afterSlideshow directive.

showPlayPause - true | false
Turns display of the slideshow play & pause controls on or off.

startPaused - true | false
If true, a slideshow will start in a paused state. If false, the slideshow will auto-play on start.

Back to Index

Tooltips & Context Boxes

See the Enhanced tooltips and Context boxes sections of the instructions for more details.

source - a content reference
Every tooltip and context box requires a 'source' reference to be defined either in data-fb-tooltip or data-fb-context. This is the reference to the content that will be shown in the tooltip or context box. Commonly, source will point to a hidden div on the page with a syntax like "source:#myDivId", but it can also be a path to any type of floatbox content. e.g., "source:`myContent.html`" to bring in an external page as the tooltip or context box content.

placement - 'bottom' | 'top' | 'left' | 'right' | 'center'
The placement option determines where an enhanced tooltip will open in relation to the host element. If the requested placement would make the tooltip appear partially offscreen, the placement will be moved over opposite to the request so that the entire tooltip shows. For example, a tooltip with placement:right which does not have room to show completely on the right side of the host element will head over to the left side, if there is sufficient room on the left. Similarly, 'top' and 'bottom' will be exchanged if necessary.

showOnce - true | false
If showOnce is set to true, a tooltip will be displayed only on the first mouse-over of the host element per browser session. A session cookie will be set in the visitor's browser that will prevent the tooltip from re-appearing for that user until a subsequent visit.

delay - milliseconds (333)
Minimum delay in milliseconds between the element mouseover event and the display of an attached tooltip.

arrowColor - css color
All tooltips, except those with placement:center set, have a small triangular arrow pointing to the host element. The default color for these arrows is to use whatever is set for outerBorderColor. Any css color can be set directly for the arrows using the arrowColor option, including 'transparent' to hide them.

arrowSize - pixels (16)
As could be guessed, the arrowSize option can be used to change a tooltip's triangular arrow size to something other than the default 16px. The arrow can be completely removed by setting arrowSize to 0. In this case, the tooltip edge will be snug up against the boundary of the host element. If 'arrowColor' is set to 'transparent', the arrowSize option can be used to specify a gap between the tooltip and the host element without filling that gap with a visible arrow.

contextMouseButton - 'both' | 'left' | 'right'
This option applies only to context boxes and sets which mouse buttons will be used to trigger the display of the context box. Mobile devices will always respond to touch gestures regardless of the contextMouseButton setting. Please see the note in the 'Context boxes' section of the instructions for information about the unreliability of right-clicks in some browsers.

Back to Index

Image/Thumbnail Cyclers

See the Cycling images and thumbnails section of the instructions for more details.

cycleInterval - seconds (6)
The number of seconds between each turnover of the displayed image in a set of cycling images or thumbnails. 'cycleInterval' applies to all cycler sets on a page and cannot be set per-cycler. All the other 'cycle*' options are per-cycler (when there is more than one cycler set on a page).

cycleFadeTime - seconds (1.7)
Controls the speed of the fade in/out of the images in a set of cycling images or thumbnails.

cycleZoom - 0-1 (0.2)
The portion of the image size to be used in the 'Ken Burns' style slow-zoom effect. Set this to 0 to turn off the effect and a smaller or larger number to decrease or increase the amount of zoom.

cycleEasing - 1-4 (1.4)
Sets the strength of the easing curve for the cycleZoom effect. (See 'easing' in this Options Reference.) If not specified, cycleEasing will use the value set in the global 'easing' option or default to 2.5.

cycleInflection - 0-1
Sets the inflection point for the easing curve of the cycleZoom effect. (See 'inflection' in this Options Reference.) If not specified, a random inflection value between 0.1 and 0.9 will be generated for each image.

cyclePauseOnClick - true | false
If set to true, a cycling image or thumbnail set can be paused and resumed by clicking or touching an image.

cycleShowControls - true | false
When cyclePauseOnClick is true, a visible play/pause control will be shown on a cycler set unless cycleShowControls has been set to false.

cycleControlsPos - 'tl' | 'tc' | 'tr' | 'bl' | 'bc' | 'br'
Controls the position of a cycler's visible play/pause control when cyclePauseOnClick and cycleShowControls are active.

cycleStartPaused - true | false
If set to true, and cyclePauseOnClick is enabled, a cycler set will begin in the paused state at page load.

cyclePauseOnHover - true | false
If set to true, image and thumbnail cyclers will pause and hold the current image while the mouse is hovered over the images. This option is ignored on mouse-less mobile devices where the concept of hovering does not exist.

Back to Index


mobile - option string | object
Options defined inside a mobile option string or object provide overrides that are set only for small-screen devices. There is a 'mobile' section in fbOptions that can be used for this purpose. A 'mobile' option can be inserted into any other option context as well, such as in 'className' and 'type' options and in per-item data-fb-options.

addVideoThumb - width | 'small' | 'medium' | 'large'
Floatbox can fetch video thumbnails from YouTube, Vimeo (public videos only) or a locally served video folder, and can auto-insert these thumbnails into floatboxed links that reference these videos. To use this option with locally served .mp4 videos, place the desired thumbnail in the same folder and with the same filename as the .mp4 video file. The fetched thumbnail will be displayed at the size specified in the addVideoThumb option which can be set to an explicit pixel width, 'small' for 120px, 'large' for 480px, or a default of 240px for 'medium' if not set. Turn addVideoThumb off by setting it to false.

addPlayButton - 'small' | 'medium' | 'large' | false
Any floatboxed anchor that contains a thumbnail can have a translucent play button displayed over top of it by setting the addPlayButton option to the desired button size (small, medium or large). The default action is to add a medium-sized play button to thumbnails added by the addVideoThumb option and to do nothing with other thumbnails. Use the addPlayButton to show a button on standard thumbnails or to change the button size for addVideoThumb thumbnails. Disable the default play button for addVideoThumb thumbnails by setting addPlayButton to false. Note that the 'small', 'medium' and 'large' settings set a size relative to the host thumbnail, and not an absolute pixel size.

fetchVideoInfo - true | false
When public videos from Vimeo are configured to show in a floatbox, the Vimeo API service is queried to fetch useful information about the video such as the title, default size, and the path to the video's thumbnail image. This can be set per-item in data-fb-options and per-page or globally.
Vimeo provides API access only for public videos and will not send any info if the video is configured as private on the Vimeo site. Setting fetchVideoInfo:false in these cases can avoid some useless network activity. If the API info is unavailable, the video link's thumbnail, along with size and caption options, will need to be configured manually.

autoPlayVideo - true | false
If the browser supports it, floatbox showing video will start automatically when the video loads unless autoPlayVideo is set to false. (Mobile browsers generally do not support auto-starting video.)
Putting "?autoplay=0" on the video link's href is equivalent to setting "autoPlayVideo:false".

autoEndVideo - true | false
A floatbox showing video, either with the built-in HTML5 video player, or from YouTube or Vimeo, will close automatically when the video ends unless autoEndVideo is set to false.
Putting "?autoend=0" on the video link's href is equivalent to setting "autoEndVideo:false".

titleAsCaption - true | false | 'a' | 'img'
If a caption is not assigned directly with the caption option, titleAsCaption, when left at its default value of true, will pull a caption in from a title attribute found on the host anchor or on a thumbnail img element within that anchor. A setting of 'a' instructs it to look at title attributes only on the anchor element and a setting of 'img' causes it to look for titles only on thumbnail img elements. To disable the setting of captions from title attributes, set titleAsCaption to false. See the 'caption' and 'caption2' options for details on how to set caption content directly. The titleAsCaption option also applies to fbCycler sets and will cause the cycler captions shown below the images to be pulled from the img elements' title attributes.

altAsCaption - true | false
If altAsCaption is set to true and a caption has not been assigned either through the caption option or as a result of the titleAsCaption option, the caption will be pulled from the alt attribute on a thumbnail image inside the floatboxed anchor. The altAsCaption option also applies to fbCycler sets and will cause the cycler captions shown below the images to be pulled from the img elements' alt attributes.

showMagCursor - 'once' | true | false
Changes the mouse cursor to a small magnifying glass when the mouse is hovered over a thumbnail in a floatboxed anchor. If set to 'once', the cursor will change only for the first mouseover on the thumbnail image. Note, that some browsers cannot and will not show the custom cursor regardless of this option's setting. (Older Opera, most Mac browsers except Safari, and some Linux browsers are guilty of this.)

modal - true | false
When modal is true, floatbox will overlay the whole page with a translucent layer, the underlying page will be unreachable until the box is closed, and any secondary floatboxes will be stacked on top of any already-opened boxes. Setting modal to false removes the translucent page overlay, allows the underlying page to be accessed while one or more floatboxes are open, and allows multiple open floatboxes to be re-arranged and restacked.

keepCentered - true | false
Floatboxes that have 'autoFit' at its default of true, or that fit entirely within the available screen, will recenter and possibly resize when the browser window is scrolled or alters its width (such as when a mobile screen is pinch-zoomed or changes orientation). Explicitly set keepCentered to true or false to force or inhibit the re-centering behaviour on any floatbox regardless of other conditions in effect.

boxScroll - true | false
The boxScroll option controls whether a floatbox will use non-scrollable, viewport-attached fixed positioning or scrollable, document-attached absolute positioning. When left unset, Floatbox will try to make intelligent choices based on modal, autofit, and pageScroll settings. Override the intelligent choice with true to make the floatbox scroll with the document, and false to exclude it from scrolling.

pageScroll - true | false
pageScroll controls the vertical scrollability of the browser window or document. When not set, vertical page scrolling will be disabled while a modal floatbox that fits entirely within the visible viewport is present. The primary pupose of this is to prevent irritating underlying page scrolls when using a mouse wheel inside the floatbox content. Set pageScroll to false to always disable page scrolling while a floatbox showing, and set it to true to never disable page scrolling. When pageScroll is disabled, the vertical scrollbar is replaced by a right-side margin of the same width to avoid content jumps and re-layout.

instanceName - string
instanceName is used in conjunction with the API function fb.getInstance to programmatically reference a particular floatbox when more than one is present. If no instanceName is provided, the default instance name will be the filename of the opening content. For example, a floatbox showing content of "/images/my_toys.jpg" without a specific instanceName assigned will be named "my_toys". See the API Reference for fb.getInstance() details.

attachTo - string
A floatbox normally inserts itself into the bottom of a host document's <body> element. Use the attachTo option to specify the id of an alternate element in which to attach the floatbox. This is particularly useful for displaying form content on ASP.NET pages, which can have only one functional form per page.

zIndex - number (77777)
Floatbox's default z-indices begin at 77777. If there is other content on a page that is set higher than this (such as maybe a navigation menu), a larger zIndex can be assigned to the floatboxes by setting this option.

framed - true | false
Normally, when floatbox.js is included on both a top page and an iframe child page, the two instances will link up and conspire to open all floatbox content in the top document, regardless of where the content originates from. There may be occasions when limiting Floatbox and its display to the confines of the iframe is desired. To do this, set the 'framed' option to true in the global section of an fbOptions definition on the iframe source page.

activateMedia ** - true | false
With 'activateMedia' left at its default of true, Floatbox will activate all links whose href refers to image, video or pdf content, without the need to set the 'floatbox' class on each of those links, or on a parent element. This is a change in behaviour from earlier Floatbox versions, and upgraders can set activateMedia to false in their global options to turn it off.

autoGallery ** - true | false
'autoGallery' works in conjunction with 'activateMedia'. In normal mode, activateMedia will activate image links as standalone items. If 'autoGallery' is set to true, all auto-activated images will be grouped and displayed together as a gallery set.
Note that if you wish other types of content to group into a gallery set automatically, simply assign a group name on the 'group' option under the file type of interest in the corresponding fbOptions:type section. If the assigned name is 'autoGallery', content of that type will be bundled in with the 'autoGallery' image set.

preloadLimit ** - number (5)
Floatbox will preload images that are set to show as floatbox content so that those images may be shown immediately when clicked instead of the visitor possibly watching the spinning loader graphic while waiting for the image to be fetched across the network. Image preloading starts shortly after the main page is fully rendered and window.onload fires so as not to intefere with page load times. preloadLimit sets the maximum number of content images that will be preloaded.

language ** - 'xx' (see the languages folder)
If the 'language' option is not set in global options then the 'lang' attribute of the active page's <HTML> element will be parsed for a usable localized language. If not found either explicitly set or in the 'lang' attribute, the default value of 'en' will assumed and English language strings will be used. To explicitly assign a language to be used by Floatbox's various strings, set the language option to one of the two letter codes that has a corresponding file available in the 'languages' folder.

floatboxClass ** ('floatbox') - className
cyclerClass ** ('fbCycler') - ...
tooltipClass ** ('fbTooltip') - ...
contextClass ** ('fbContext') - ...
The class names that are used to activate floatbox elements can be changed in order to avoid conflicts with other html and css. For example, if the 'floatbox' class is already used for other purposes, the floatboxClass option could be changed to 'floater' or any other unused class name.

** 'activateMedia', 'autoGallery', 'preloadLimit', 'easing', 'inflection, 'animationTime', 'language', and the 4 '*Class' names cannot be set as type, class or item options. They can be set only in the global section of fbOptions.js or a page-specific fbOptions javascript object.

Back to Index


Options in this section do not have default values defined. While most of these options can be applied globally, per page, per type and per class, they usually make sense only when assigned on a per item basis.

group - string
Anchors that have the same group option set on them will form a gallery set that can be navigated with the prev/next buttons or shown as a slideshow.

width - pixels | 'xx%'
height - pixels | 'xx%'
Width and height set in the options control the size of a floatbox's content element. Plain integers are the size in pixels. If a percentage is given, like "85%", floatbox will be sized to that portion of the available browser viewport area. Width and height options can apply to images, but they're intended primarily for html and multimedia content. For images, it's best to serve images that are already sized to what they should be displayed at, which also ensures maintenance of correct proportions when resizing occurs. Note that for HTML content (ajax, inline, iframe or direct), it's best to set only a width, either in the options or in the HTML content styles, and let floatbox measure and auto-set the content height. This allows floatbox to get correct sizing across different browsers that have small variations in the way they layout pages.

aspect - number
The aspect option defines the aspect ratio (width to height ratio) of floatbox content; usually video content, but can be applied to any content type. Internally, Floatbox defaults video to an aspect ratio of 16/9. Videos with a different aspect ratio should specify that ratio in the 'aspect' option to auto-fit different screens correctly.

contentScroll - true | false
The contentScroll option controls the display of the scroll bars on the floatbox when showing html content. The default setting of true allows most browsers to show scrollbars if needed and not show them if the content is not larger than the containing box. Set contentScroll to false to prevent scrollbars in HTML content.

caption - string | #hiddenDivId
caption2 - ...
To display a caption in floatbox, use the title attribute of an <a> or <img> element when 'titleAsCaption' is set to true, use the alt attribute of an <img> when 'altAsCaption' is set to true, or set the 'caption' option in the anchor's data-fb-options attribute. Using the default 'titleAsCaption' capability is recommended because it required no additional markup for auto-activated media content.
When assigned explicitly in a data-fb-options attribute, the text of the caption option must usually be surrounded by backquote characters (`) so as not to break parsing of the option string.
Example: data-fb-options="caption:`This is my kool kaption`"
The caption options can also be set to 'href' to parse out a suitable caption from the link's href filename.
A second caption can be assigned to a floatbox item by setting 'caption2' in the same manner as 'caption'.
The easiest way to include html content in a caption is to reference a hidden div that contains the desired content, like this: data-fb-options="caption:#myCaptionDiv"
It's also possible, but more difficult, to place encoded HTML directly in the caption string. See the "Captions" section of the instructions for details.

header - string | #hiddenDivId
footer - ...
Display transparent-background content immediately above or below the floatbox with the header and footer options. These can be set in the same manner as captions described above, and can use direct text, encoded html, or a reference to a hidden div (recommended). Although described here in the item-specific section of this options reference, like all options header and footer can be assigned globally, per page, by type, and by class name.

type - 'ajax' | 'video' | 'image'
Floatbox auto-detects content type based on the href file extension, but there are occasions where auto-detection can't work. Two examples are content that is to be loaded via AJAX and iframe-based video embeds. Load AJAX content by setting "type:ajax" in the anchor's data-fb-options attribute. This tells Floatbox that what would otherwise appear to be a request to load an iframe content page should instead load an HTML snippet via AJAX. For iframe-based video, set "type:video" in the options. (There's no need to set type:video for mp4 files, YouTube, or Vimeo. Floatbox already knows what these are.) Sometimes images are delivered by .php or .aspx server-side scripts, and these would need "type:image" on their links to be recognized as such.

showThis - true | false
An anchor with "showThis:false" in its data-fb-options attribute will not be added to a gallery or slideshow collection. However, other options set on the anchor will take effect. The showThis option is there primarily to enable a clickable link to display a gallery as a slideshow. Such a link would have at least the following in its options attribute: data-fb-options="showThis:false doSlideshow:true group:xyz". The 'group' option is necessary to identify which gallery set this link is associated with.

sameBox - true | false
The default behaviour when floatboxed content is invoked while an existing floatbox is already being displayed is to display the new content in a new secondary floatbox over top of the existing one. Use sameBox:true to cause the new content to replace the existing content within the existing floatbox and not open up a second box.

newWindow - true | false
'newWindow' makes sense only when used inside a 'mobile' option set for small-screen devices. It instructs those devices to open the content in a new browser tab or window, rather than showing it inside a floatbox. In an unmolested fbOptions.js file, "newWindow:true" is set for mobile devices loading content type 'pdf'.

altContent - string
Provide alternate content for floatboxed images and iframes by assigning text to the 'altContent' option. Use of altContent provides text for screen-readers and enhances a site's Section 508 accessibility compliance.

info - source reference
Assigning a url or other source type to the info option will make floatbox display an "Info..." link that will load the referenced source in a new secondary floatbox. The 'infoOptions' and 'infoText' options can be combined with 'info' to control the appearance and behaviour. See the instructions and demo for more details.

useMap - id
An image shown as floatbox content can have an area-map assigned to it by setting the useMap option. The map element should be defined on the base page and have an id attribute set on it. Reference this id as the value of the useMap option. A name attribute on the map element and a reference to that name will not be sufficient to find it; use an id. Note that the areas in the map can themselves have floatboxes, tooltips, and context boxes assigned to them. An area map assigned to a floatboxed image will always scale appropriately with the images as it is resized or auto-fit to the viewport.

source - source reference
A "source:`...`" option, usually set in the data-fb-options attribute, will override the href defined on a floatbox-enabled anchor. Floatbox will use the source option value, while browsers with javascript disabled will load the anchor's standard href value. This can be used to provide alternate content for javascript-disabled clients. 'source' can be any content type (url, ajax, inline div, or direct html).

className - string
Setting 'className' in the options is, in most contexts, equivalent to assigning the 'class' attribute on a starting link. Being able to set className directly in the options allows for including another set of className based options into the current definition, can be used to apply class options in fb.start() API calls, and can be handy for assigning class options to fbTooltips or any other or any links where messing with the class attribute is not desired.

autoStart - 'once' | true | false
Place "autoStart:true" in the options assigned to a floatbox-enabled <a> element to automatically start the associated content (referenced by the href attribute) at page load time without the user clicking on anything. An autoStart setting of 'once' will cause that item to auto-start only on the first load of the page per browser session. Note that autoStart can also be set in the page's query string, as described in the instructions document.

autoDelay - seconds (0)
A floatboxed link with 'autoStart' set on it normally opens as soon as the document and Floatbox software are loaded and ready for use. Set 'autoDelay' to a number of seconds to make the floatbox wait a set period of time before auto-starting.

autoEnd - seconds (0)
Any floatbox can be set to automatically close after a set period of time. This is particularly useful for enhanced tooltips that should show for 5 seconds or so and then get out of the way. It could also be used to alienate site visitors by combining autoStart and autoEnd to show an interstitial ad for a set period of time in a floatbox that has all other mechanisms and controls for closing the floatbox disabled.

loadPageOnClose - 'self' | 'back' | url
This controls browser behaviour when a floatbox closes. If set to the string 'self', the host page will be refreshed on exit. If set to 'back', the previous page in the browser's history list will be loaded. If loadPageOnClose is set to a string other than 'self' or 'back', that string is assumed to be a valid url and the browser will be instructed to load that page. When loadPageOnClose is set to a url, it typically needs to be be enclosed in backquotes (`) so as not to break parsing of the option string. The loadPageOnClose option applies only to standard floatboxes and will not fire when a tooltip or context box closes. Note that when using the API call 'fb.end()' to close a box, the loadPageOnClose value can be passed directly to that function as a parameter. E.g., fb.end('/somePage.html') See the API reference for details.

  • noFocus - true | false
  • noFocus - true | false
    When loading HTML content that contains text input form elements, the first text input will normally be focussed and thus ready to accept keyboard input. Disable this auto-focus behaviour by setting the noFocus option to true.

    order - number
    A Floatbox gallery set shows the images in a Floatbox in the order in which they appear within the document. Set a different order on the gallery set members by assigning order numbers to the member items. The set will be sorted in the numerical order of the assigned values.

    Back to Index

    Event Callbacks

    beforeBoxStart - function | eval string
    afterBoxStart - ...
    beforeItemStart - ...
    afterItemStart - ...
    beforeItemEnd - ...
    afterItemEnd - ...
    beforeBoxEnd - ...
    afterBoxEnd - ...
    beforePrint - ...

    The Floatbox interface includes various event callbacks that run assigned code at various points in a floatbox's life-cycle. The callbacks are setup as Floatbox options to which javascript functions or code is assigned. The callback options are assigned their values in the same manner as other options and can be defined in fbOptions or on an anchor's data-fb-options attribute.
    Callbacks defined in a page's fbOptions definition can be either true javascript functions or strings to be eval'd.
    Callbacks set in an anchor's data-fb-options tag can be the name of a global function to be called or a string of javascript code to be eval'd.

    If any of the before* callback functions return a value of false, the associated Floatbox action will be cancelled.
    This does not apply to eval'd text strings; they don't return values and so cannot cancel Floatbox actions.

    Some callback functions will receive an argument that is the active floatbox instance. This might be handy for something like checking the state of the HTML within fbContent prior to allowing a box end to occur. The callbacks that receive the instance parameter are beforeItemStart, afterBoxStart, afterItemStart, beforeItemEnd, beforeBoxEnd and beforePrint.

    Example - A function callback in the page options:

    function myFunc () { alert( 'eat a peach' ); return true; } fbOptions = { global: { beforeBoxStart: myFunc } };

    And a string callback in an anchor's data-fb-options attribute:

    <a href="xyz.php" class="floatbox" data-fb-options="afterItemEnd:`myFunc();`" > talk about fruit </a>
    (Don't forget the back-quotes. They're often required for correct parsing of code strings.)

    That previous example could be simplified to just the defined function's name:

    <a href="xyz.php" class="floatbox" data-fb-options="afterItemEnd:myFunc" > talk about fruit </a>

    beforeBoxStart is executed prior to a floatbox being started by either a click on an activated anchor or by an API fb.start call.
    It could be used to check that desired conditions have been met before starting up the floatbox, and cancelling the box start by returning false from the assigned function if the conditions are not right.

    beforeItemStart differs from beforeBoxStart only when a gallery set of items is being displayed. beforeItemStart will fire whenever the associated gallery set item is shown whereas beforeBoxStart will not fire when the floatbox navigates to new content in a set. If the beforeItemStart returns false from an assigned function, the floatbox will not start if it is just starting up, or else will not navigate if it is responding to a previous or next command in a gallery set.

    afterBoxStart runs as soon as a new floatbox is initially created. It differs from beforeBoxStart in that it cannot cancel the floatbox's creation and it receives a single parameter which is a reference to the newly created floatbox instance.
    afterBoxStart could be used to tweak or modify some of the components in the referenced floatbox.

    afterItemStart runs whenever new content is shown in a floatbox, either because the floatbox has just started, or because the associated item has just been invoked by a 'previous' or 'next' action in a gallery set.
    The afterItemStart function receives a reference to the current floatbox instance and may be used to setup initial states or behaviours in the freshly arrived content. It can be considered as similar to a window.onload event where the 'window' is the floatbox display area (fbContent).

    beforeItemEnd is fired whenever a currently showing item is about to go away, either from its host floatbox closing, or from a gallery set navigation. It receives a single parameter that is a reference to the current floatbox and could be used to check that required conditions in the content have been met. The beforeItemEnd function can cancel a pending floatbox end or navigation by returning false.
    For example, suppose we have a quiz with a series of multiple choice questions shown as a multi-question gallery set. beforeItemEnd could check that an answer has been selected and, if not, could alert that all questions must be answered and then return false to cancel navigation to the next question.

    beforeBoxEnd is fired prior to a floatbox closing, receives a parameter of current floatbox instance, and can return false to cancel the closing of the floatbox.
    It could, for example, be used to ask for confirmation before closing a displayed shopping cart that had unprocessed items in it.

    afterItemEnd will fire whenever a floatbox item goes away, either because the floatbox has closed or because a gallery set has navigated to a new item.
    This is probably the least useful of Floatbox's callbacks and is provided primarily for consistency. It could be used for something obscure like sending an AJAX notification back to the server that reports how long the departing item was viewed.

    afterBoxEnd fires when a floatbox has finished closing in response to one of the close controls or from an API fb.end call.
    This is useful in an interactive web page to invoke an action or behaviour when the user is finished with the floatbox and closes it. (Note: Page refreshes and navigation are best done with the 'loadPageOnClose' option, or from script using the 'fb.end()' API function.)

    beforePrint will fire whenever Floatbox's node printing capability is invoked, whether directly through the fb.printNode API function or through the 'showPrint' option.
    Use this to manipulate content prior to printing, or perhaps to display a message or disclaimer. Returning false from the beforePrint function will cancel the print request.

    Back to Index