Overview

The following is a complete list of all the configuration options for Juicebox.

Juicebox-Lite accepts the Lite Options and the Embed Options. To unlock the Pro options, upgrade to Juicebox-Pro.

If an option is not specified, it will use the default value specified below.

For instructions on how to set options, check here.

Some options are marked as (Large Screen Mode only). To read more about Screen Modes, check here.

Lite Options

Options supported by Lite version.

Option Name Default Value Description
galleryTitle "" Text to display as the gallery Title.
galleryWidth 100% Pixel or percentage width of the gallery. Must be specified in the embed code.
galleryHeight 100% Pixel or percentage height of the gallery. Must be specified in the embed code.
backgroundColor #222222 Gallery background color as a CSS3 color value. Can be either a hexidecimal value "FF00FF" or a RGBA value: "rgba(10,50,100,0.7)". (Large Screen Mode only.)
textColor rgba(255,255,255,1) Color of all gallery text. (Large Screen Mode only.)
thumbFrameColor rgba(255,255,255,.5) Color of the thumbnail frame when thumbnail is selected or rolled over. (Large Screen Mode only.)
showOpenButton TRUE Whether to show the 'Open Image' button. Images are opened in a new tab to allow image downloading.
showExpandButton TRUE Whether to show the 'Expand' button. Clicking this button expands the gallery to fill the browser window. Expand button only displays if the gallery is embedded at less than 100% of the browser window size. More details.
showThumbsButton TRUE Whether to show the 'Toggle Thumbnails' button in Large Screen Mode.
useThumbDots FALSE Replace the thumbnail images with small dots. See example. Large Screen Mode only. Disabled for 'thumbsPosition' LEFT or RIGHT.
useFullscreenExpand FALSE

Triggers fullscreen mode when clicking the 'expand' button for supported browsers (Firefox, Safari and Chrome).

useFlickr FALSE Whether to use Flickr as the source of the images and text. If set to TRUE and no user name or tags are specified, Juicebox will fetch Flickr's current most interesting images.
flickrUserName "" The Flickr user name of the photos to display. If this parameter isn't passed, then everybody's public photos will be searched. To get your Flickr User Name, check here.
flickrTags "" A comma separated list of tags. Photos with one or more of the tags listed will be returned. Can be used in conjunction with Flickr Pro Option flickrTagMode.
languageList   Used to specify translated international language for gallery display text (mainly button tooltips). View details.

Embed Options

Embed options are useful if you don't want to use the standard Juicebox gallery file structure. Set these options in the embed code. See 'Embed Code Options' in this section.

Option Name Default Value Description
containerId juicebox-container Id of the HTML div to replace with the Juicebox gallery.
configUrl config.xml Relative or absolute URL of the config XML file. Useful if you want to load gallery XML data from somewhere other than the default location.
themeUrl classic/theme.css

Relative or absolute URL to the theme CSS file. Useful if you want to load a theme from a different location than the default.

If themeUrl is not specified, Juicebox will look for the theme CSS relative to the juicebox.js file (classic/theme.css).

baseUrl ""

Relative or absolute URL of the gallery folder. Useful when embedding Juicebox into a HTML page that is outside the gallery folder. View more info here.

If set, all relative URLs to gallery content (imageUrls, thumbUrls and configUrl) will be relative to this URL.

debugMode FALSE If set to TRUE, allow setting config options via the URL query string. Must be set in the config XML file.

General Options

General gallery-wide options.

Option Name Default Value Description
screenMode AUTO

This option allows the user to force a Screen Mode for all devices. It is recommended to set this to "AUTO" to best handle all devices. Can be:

  • AUTO
  • LARGE
  • SMALL
enableDirectLinks FALSE

If true, navigating to a new image will navigate to a new URL in the browser address bar, like this: http://www.mysite.com/mygallery/#12 allowing the user to use the Back Button to step back through images. This option also enables direct links to a specified image in a gallery by appending the image id.

enableKeyboardControls TRUE

Whether keyboard can be used to control the gallery. The gallery must be clicked on by the user to enable keyboard controls. Supported keys are:

  • Next Image - Cursor Right, J
  • Prev Image - Cursor Left, K
  • Toggle AutoPlay - Spacebar
  • First Image - Home Key
  • Last Image - End Key
expandInNewPage AUTO

Controls how galleries behave when the user clicks the 'Expand Gallery' button. Expanded galleries can either open in the same page or in a new page. See here for more details. Can be:

  • AUTO - If not on iOS open in same page. If on iOS and viewport is locked, open in same page. If on iOS and viewport is not locked, open in a new page.
  • TRUE - Always open in a new page
  • FALSE - Always open in the same page. For this to work correctly on iOS, the gallery page must have a locked viewport.
firstImageIndex 1 Index of the image to display when the gallery loads. Images are numbered starting at 1.
randomizeImages FALSE If set to TRUE, images are randomly shuffled each time the gallery is loaded.
enableLooping FALSE Whether navigating or autoplaying beyond the last image loops back to the first image.
stagePadding 0 Amount of padding to show around the entire gallery in pixels. (Large Screen Mode only.)
topAreaHeight 50 Height of the top area in pixels. The top area is a horizontal strip displayed if buttonBarPosition or galleryTitlePosition are set to 'TOP'. (Large Screen Mode only.)
galleryTitlePosition OVERLAY

Position of gallery title. Can be:

  • OVERLAY - Gallery title sits over main image
  • TOP - Gallery title sits above main image
  • ABOVE_THUMBS - Gallery title sits above the thumbnail area
  • NONE
galleryTitleHAlign LEFT

Horizontal alignment of the gallery title. (Large Screen Mode only.) Can be:

  • LEFT
  • CENTER
  • RIGHT
galleryFontFace Font face to use for titles, captions and other gallery text. Comma delimited list of font-faces, with +s for spaces. For example: "Helvetica+Neue,Helvetica,Arial,sans-serif". Fonts must be installed on the viewing device to be displayed.
galleryDescription "" Optional gallery description text. Used for the SSM Splash Page, Open Graph tags, and SEO content.

Color Options

Customize the gallery interface colors with these options. For more advanced customization, you can modify the CSS directly by creating a custom theme. Colors are specified as a CSS3 color value in the format: "FF00FF" or "rgba(10,50,100,0.7)". (Large Screen Mode only.)

Note - RGBA colors are not supported in Internet Explorer 6 and 7. RGBA colors will be automatically converted to the equivalent hexadecimal color when viewed with IE 6 and 7.

Option Name Default Value Description
captionBackColor rgba(0,0,0,.3) Color of the caption background area. (Large Screen Mode only.)
buttonBarBackColor rgba(0,0,0,.5) Color of the Button Bar background. To set icon colors, create a custom theme. (Large Screen Mode only.)
imageFrameColor rgba(255,255,255,1) Color of the optional image frame. (Large Screen Mode only.)
topBackColor rgba(0,0,0,0) Color of the top section. Top section is displayed if either backButtonPosition, galleryTitlePosition or buttonBarPosition is set to 'TOP'. (Large Screen Mode only.)
imageShadowColor rgba(0,0,0,0.4) Color of shadow around main image.
textShadowColor rgba(0,0,0,0.5) Color of shadow around caption and title text.
thumbShadowColor rgba(0,0,0,0.4) Color of shadow around thumbnails.
thumbDotColor rgba(0,0,0,0.4) Color of thumb dots.
thumbDotHoverColor rgba(255,255,255,1) Color of thumb dots when hovered with the mouse.
buttonBarIconColor rgba(255,255,255,1) Color of button bar icons.
buttonBarIconHoverColor rgba(255,255,255,1) Color of button bar icons when hovered with the mouse. Mouse Input Mode Only.
navButtonIconColor rgba(255,255,255,1) Color of navigation button icons.
navButtonIconHoverColor rgba(255,255,255,1) Color of navigation button icons when hovered with the mouse. Mouse Input Mode Only.
navButtonBackColor rgba(0,0,0,0.5) Color of navigation button background area.
expandedBackgroundColor #222222 Color of gallery background when gallery is expanded.

Main Image Options

Controls appearance and behavior of the main image.

Option Name Default Value Description
imageTransitionType SLIDE

How to transition between images. Only applies for Large Screen Mode and Mouse Input Mode. Can be:

  • SLIDE Previous image slides out while next image slides in.
  • FADE: Previous image fades down to background color then next image fades in.
  • CROSS_FADE: Crossfade between previous and next image.
  • NONE: No transition. Next image pops in.
imageHAlign CENTER

Horizontal alignment of the image within the image area. (Large Screen Mode only) Can be:

  • LEFT
  • CENTER
  • RIGHT
imageVAlign CENTER

Vertical alignment of the image within the image area. (Large Screen Mode only) Can be:

  • TOP
  • CENTER
  • BOTTOM
imageClickMode NAVIGATE

Determines what happens when the user clicks on an image. Can be:

  • NAVIGATE - Enables Previous/Next image navigation via Image Navigation Arrows.
  • OPEN_URL - Enables left-click image to open a URL. Opens optional ‘linkURL’ + linkTarget’ in image tags, or defaults to imageURL. Setting this to true disables image navigation.
  • NONE - Image click has no action.
imageScaleMode SCALE_DOWN

Determines how the main image is scaled to fit the available area. Can be:

  • SCALE_DOWN: Scale large images down to fit Image Area, maintaining aspect ratio. Will not scale images up, which can reduce image quality.
  • SCALE: Scale images up AND down to fit Image Area, maintaining aspect ratio.
  • FILL: Scale images up and down to completely fill Image Area. Large images are cropped to fit image area.
  • STRETCH: Stretch image to exactly fit Image Area, losing image's aspect ratio.
  • NONE: No scaling. Large images are cropped to fit Image Area.
imagePreloading PAGE

Determines how images are preloaded. Also controls if images are kept in memory after being viewed. (Large Screen Mode only.) Can be:

  • PAGE - Preloads all images in the current thumbnail page. Unloads all images in the previous thumbnail page.
  • NEXT - Preloads image after currently viewed image. Unloads previously viewed images.
  • ALL - Preloads all images in gallery. Maximum usability. Images never unloaded. Not good for large galleries (image count > 50).
  • NONE - No image preloading. Conserves server bandwidth at cost of slower responsiveness.
imageTransitionTime .5 Image transition tween length (seconds). Use for main image slide, and thumb slide.
imagePadding 0 Amount of padding to show around the main image in pixels. (Large Screen Mode only.)
showImageOverlay AUTO

When to show the image overlay. Can be:

  • AUTO - For mouse devices, show overlay when mouse is over the gallery, hide it when mouse is outside. For touch devices, tap screen to toggle overlay.
  • ALWAYS - Always show image overlay.
  • NEVER - Never show image overlay.
showOverlayonLoad TRUE Whether to show the image overlay when the gallery is first loaded.
showImageNav TRUE Whether to show the image naviagtion buttons (arrow buttons that overlay the main image).
imageNavPosition STAGE

The position of the main image navigation arrow buttons. Can be:

  • STAGE - Nav button positions are relative to the stage area. Position does not change as image size changes.
  • IMAGE - Nav button positions are relative to the current image. Position changes as the image size changes.
imageNavPadding 20 Distance between edge of stage (for imageNavPosition = STAGE) or image (for imageNavPosition = IMAGE) and edge of image nav button (pixels). (Large Screen Mode only).
frameWidth 0 Width of the frame around the main image (pixels). (Large Screen Mode only).
imageCornerRadius 0 The radius of the the main image corners (pixels). Allows a rounded main image.
changeImageOnHover FALSE Whether to change the main image as the user mouses over the thumbnails (Large Screen Mode only).
imageShadowBlur 10 The amount of blurring of the main image shadow (pixels).
navButtonIconSize 20 The size of the navigation button icons (pixels).

Thumbnail Options

Controls the thumbnail images.

Option Name Default Value Description
thumbWidth 85 Width of the thumbnail images (pixels).
thumbHeight 85 Height of the thumbnail images (pixels).
thumbsPosition BOTTOM

Position of thumbnails. Can be:

  • TOP - Above the main image.
  • BOTTOM - Below the main image.
  • LEFT - Left of the main image.
  • RIGHT - Right of the main image.
thumbsHAlign CENTER

Horizontal alignment of the thumbnails within the thumbnail area. (Large Screen Mode only) Can be:

  • LEFT
  • CENTER
  • RIGHT
thumbsVAlign CENTER

Vertical alignment of the thumbnails within the thumbnail area. (Large Screen Mode only) Can be:

  • TOP
  • CENTER
  • BOTTOM
maxThumbColumns 10 The maximum number of thumbnail columns that will be displayed. The number of thumbnail columns is dynamically calculated from the size of the screen and the size of the thumbnail images.
maxThumbRows 1 The maximum number of thumbnail rows that will be displayed. The number of thumbnail columns is dynamically calculated from the size of the screen and the size of the thumbnail images.
showThumbsOnLoad TRUE Whether to show the thumbnail images below the main image in Large Screen Mode when gallery is loaded.
showSmallThumbsOnLoad TRUE Whether to show the thumbnail page in Small Screen Mode when gallery is loaded.
showSmallThumbsButton TRUE Whether to show the thumbnail button in Small Screen Mode.
showSmallThumbNav FALSE Whether to show the thumbnail next and back page buttons in Small Screen Mode.
thumbPadding 10 Space between the thumbnail images (pixels).
showPagingText FALSE Whether to show 'Page X of Y' text under the thumbnail images in Large Screen Mode.
showSmallPagingText TRUE Whether to show 'Page X of Y' text under the thumbnail images in Small Screen Mode.
thumbNavPosition CENTER

Position of thumbnail navigation arrows. Can be:

  • CENTER - Vertically centered in the thumbnail area.
  • BOTTOM - Below the thumbnail area.
thumbFrameWidth 0 The width of the thumbnail frame in the default state (pixels).
thumbHoverFrameWidth 2 The width of the thumbnail frame when the mouse is over the thumbnail (pixels).
thumbSelectedFrameWidth 10 The width of the thumbnail frame when the thumbnail is selected (pixels).
thumbCornerRadius 0 The radius of the the thumbnail corners (pixels). Allows rounded thumbnail corners.
thumbShadowBlur 5 The amount of blurring of the thumbnail shadow (pixels).

Button Bar Options

The Button Bar is a set of buttons at the top-right of the gallery that allows gallery control. Also check the 'showOpenButton, 'showExpandButton' and 'showThumbsButton' in the Lite Options above.

Option Name Default Value Description
buttonBarPosition OVERLAY

Position of the Button Bar. Can be:

  • OVERLAY - Button Bar sits over main image. Button bar position is relative to the entire stage.
  • OVERLAY_IMAGE - Button Bar sits over main image. Button bar position is relative to the main image.
  • TOP - Button Bar sits above main image
  • NONE
buttonBarHAlign RIGHT

Horizontal alignment of the Button Bar. Can be:

  • LEFT
  • CENTER
  • RIGHT
showAutoPlayButton FALSE Whether to show the 'Toggle AutoPlay' button.
showAudioButton FALSE Whether to show the 'Toggle Audio' button.
showInfoButton FALSE Whether to show the 'Toggle Info' button. The 'Toggle Info' button toggles the visibility of the image overlay. The image overlay includes the gallery title, the image caption and the image navigation buttons. If set to TRUE, then the default behaviour controlling overlay visibility is disabled.
showNavButtons FALSE Whether to show the previous and next image navigation buttons in the Button Bar. These buttons can be used in addition to the image navigation buttons.
buttonBarIconSize 20 The height of the button bar icons (pixels).

Caption Options

Control appearance of text captions.

Option Name Default Value Description
captionPosition OVERLAY

Position of the caption and title relative to the main image (Large Screen Mode only). Can be:

  • OVERLAY - caption sits over the main image. Caption width matches entire stage.
  • OVERLAY_IMAGE - caption sits over the main image. Caption width matches the main image.
  • BELOW_IMAGE - caption placed between main image and thumbnails. Caption width matches the main image.
  • BOTTOM - caption placed at bottom of gallery. Caption width matches entire stage.
  • BELOW_THUMBS - caption placed under thumbnails. Caption width matches thumbnail area.
  • NONE
captionHAlign LEFT

Horizontal alignment of the caption text within the caption area. Image number text always stays on the right of the caption area. Can be:

  • LEFT
  • CENTER
  • RIGHT
maxCaptionHeight 120 The height of the caption area. When captionPosition is set to BELOW_IMAGE, BOTTOM or BELOW_THUMBS, the area uses this value. For OVERLAY captions this value determines the maximum possible height of a caption.
showImageNumber TRUE Whether to show the "3/14" image number text in the caption.

Background Image Options

Control appearance of optional background image to display behind the gallery.

Option Name Default Value Description
backgroundUrl ""

Relative or absolute URL to a JPG, PNG or GIF image to load as the gallery background.

backgroundScale STRETCH

Defines how the background image is scaled to fit the gallery. Can be:

  • STRETCH - Stretch image to exactly fill gallery, losing image's aspect ratio.
  • FILL - Scale image to completely fill gallery without losing image aspect ratio. Image may be cropped to fill.
  • NONE - No scaling.

AutoPlay Options

AutoPlay mode allows hands free viewing. See also showAutoPlayButton option

Option Name Default Value Description
enableAutoPlay FALSE Whether to enable AutoPlay via the AutoPlay button and space bar.
autoPlayOnLoad FALSE Whether to automatically start playing when the gallery is loaded.
displayTime 5 Number of seconds each image will display for in AutoPlay mode. AutoPlay will always wait for the next image to be loaded before showing it, so this is the minimum display time.
showAutoPlayStatus TRUE Whether to show the "AutoPlay ON/OFF" message when user toggles autoplay mode.
goNextOnAutoPlay FALSE Whether to immediately navigate to the next image when the AutoPlay mode is turned on.

autoPlayThumbs
TRUE Whether to navigate the thumbnail images to match the current main image when autoplaying.

Audio Options

Control optional audio to play while viewing the gallery. See also showAudioButton option. For more details on adding audio, check here. Note - Audio options are not supported in Internet Explorer version 8 and below.

Option Name Default Value Description
audioUrlMp3 ""

Relative or absolute URL for the audio MP3 file (e.g. "music.mp3").

audioUrlOgg ""

Relative or absolute URL for the audio OGG file (e.g. "music.ogg"). OGG files are required for playback in Firefox.

loopAudio TRUE Whether to loop the audio forever.
playAudioOnLoad FALSE Whether to automatically start the audio when the gallery is loaded. Note - this option is not supported on iOS or Android.
audioVolume 0.8 Audio playback volume. Number between 0 (silent) and 1 (full volume).

Sharing Options

Allows sharing gallery images via social networks. Also includes options to add a shopping cart and SEO Content. View Sharing SEO and Shopping Cart details here.

Option Name Default Value Description
shareFacebook FALSE Whether to display a button to share images on Facebook.
shareTwitter FALSE Whether to display a button to share images on Twitter.
shareGPlus FALSE Whether to display a button to share images on Google Plus.
sharePinterest FALSE Whether to display a button to share images on Pinterest.
shareTumblr FALSE Whether to display a button to share images on Tumblr.
fotomotoStoreId To use Fotomoto, enter your Fotomoto Store Id here. View Details. A shopping cart icon will be displayed
shareURL Absolute URL of the gallery, used for sharing purposes. This should be the absolute URL of the web page the gallery is embedded in, not including the HTML file name, for example: "http://www.example.com/mygallery/". This URL is used to populate the sharing content.
addSEOContent TRUE Whether to add gallery text and images as Search Engine indexible content.

Back Button

Optional Back Button appears at gallery top-left and offers a way for users to navigate away from a full browser gallery. Can be used to link to any URL. By default, the Back Button navigates to the last page in the browser history.

Option Name Default Value Description
backButtonPosition NONE

Position of the Back Button. (Large Screen Mode only) Can be:

  • TOP - Back Button sits above the main image
  • OVERLAY - Back Button sits at top of main image
  • NONE - Back Button does not show
backButtonUseIcon FALSE Whether to use a 'home' icon button as the back button.
backButtonHAlign LEFT

Horizontal alignment of the Back Button. (Large Screen Mode only) Can be:

  • LEFT
  • CENTER
  • RIGHT
backButtonText < Back Display HTML text for the optional Back Button.
backButtonUrl "" Relative or absolute URL to navigate to when clicking the Back Button. If set to "", the Back Button goes back one page in the browser's history.
showSmallBackButton FALSE Whether to show the back button in small screen mode.

Splash Page

These options are used by the Small Screen Mode Splash Page. More details here.

Option Name Default Value Description
showSplashPage AUTO

If set to AUTO, the Splash Page will show in Small Screen Mode and embedded at less than 100%. Can be:

  • AUTO
  • ALWAYS
  • NEVER
splashButtonText View Gallery Text to show on the Splash Page.
splashTitle "" If not specified, defaults to galleryTitle.
splashImageUrl "" Absolute or relative URL of the image to be used for the Splash Page. If not specified, defaults to the 1st image in the gallery.
splashShowImageCount TRUE Shows 'X Images' text.

Flickr Pro Options

Fine grain control over Flickr image loading.

Option Name Default Value Description
flickrUserId ""

Can be used instead of flickrUserName. Get a Flickr user id here.

Example: "48508968@N00"

flickrSetId ""

The id of the photoset to return the photos for. (Overrides flickrUserName and flickrTags.) To get a Flickr set id, go to the set's Flickr page. The id is the last numerical string in the URL.

Example: "72157624436414524"

flickrGroupId ""

The id of a group who's pool to search. If specified, only matching photos posted to the group's pool will be returned. The first (one) flickrTags can also be used in a group search. Get a Flickr Group Id here.

Example: "13813978@N00"

flickrTagMode ALL

Defines how multiple tags are combined for a Flickr tag search. Can be:

  • ALL - use AND combination (image must have all tags to be displayed)
  • ANY - use OR combination (image can have 1 or more tags to be displayed)
flickrSort DATE-POSTED-DESC

The order in which to sort returned photos. Defaults to DATE-POSTED-DESC. Can be:

  • DATE-POSTED-DESC
  • DATE-POSTED-ASC
  • DATE-TAKEN-DESC
  • DATE-TAKEN-ASC
  • INTERESTINGNESS-DESC
  • INTERESTINGNESS-ASC
  • RELEVANCE

Note this option does not work for set and group searches which always use the Flickr set display order. To change the order of images in a Flickr set, check here.

flickrImageSize LARGE

Image size to load from Flickr. Can be:

  • MEDIUM - 500 on longest side
  • LARGE - 1024 on longest side (only exists for original images larger than 1280). If the large version does not exist, Juicebox will fetch the medium version.
  • ORIGINAL - Original uploaded image dimensions. To access the original image size, the Flickr user must have a Flickr Pro Account and the image's privacy must be set to public and its license set to Attribution-NonCommercial-ShareAlike Creative Commons. Check here for more info.
flickrImageCount 50 Number of images to return in a Flickr gallery. Can be from 1 to 500. More images take longer to load.
flickrExtraParams "" A comma-separated list of additional parameters to be passed to a tag search. View a list of possible values here. Enter params in this format: "content_type=2,has_geo=1"
flickrShowTitle TRUE Whether to show the Flickr image's title in the caption.
flickrShowDescription FALSE Whether to show the Flickr image's description in the caption.
flickrShowPageLink FALSE Whether to show a link to the Flickr image's photo page in the caption.
flickrPageLinkText "View Photo Page" Text used for the Flickr caption page link.