nanogallery2 nanogallery2

nanogallery2 documentation

Some concepts

Basically, to build a gallery, you need to use some content and to define a layout.

1. Gallery content

A gallery is made of items which are composed of an image and/or a thumbnail image, and optional meta-data (title, description, location, exif data, etc.).
List all items with their meta-data in you HTML page. Or, use a data provider to automatically fetch your content to the gallery.
Full usage description is available on the content source page.

  • Self hosted images
    Items are defined in your HTML page.
              <div id="my_nanogallery2" data-nanogallery2>
                <a href="img_01.jpg" data-ngthumb="img_01t.jpg" >Title Image1</a>
                <a href="img_02.jpg" data-ngthumb="img_02t.jpg" >Title Image2</a>
                <a href="img_03.jpg" data-ngthumb="img_03t.jpg" >Title Image3</a>

  • Self hosted images with module nanoPhotosProvider2
    nanoPhotosProvider2 is a PHP application for your webserver.
    In your page, just point nanogallery2 to your webserver to automatically get all images stored there.
    Usage example:
              <div id="nanogallery2" data-nanogallery2='{
                  "kind":             "nano_photos_provider2",
                  "dataProvider":     "",
                  "thumbnailHeight":  150,
                  "thumbnailWidth":   150

  • Modules for cloud storage
    Optional modules exist to fetch images from Flickr or Google Photos.

2. Gallery layout

3 basic layouts are available: grid, justified and cascading.

  • Grid layout
    All thumbnails have the same size. Define the height and the width of the thumbnails. Images may be cropped to fit the thumbnail.


    thumbnailWidth: 300, thumbnailHeight: 200

  • Justified layout
    The width of the thumbnail is calculated to respect the image ratio. There's no cropping and no reordering.
    Set the special value 'auto' to thumbnailWidth


    thumbnailWidth: 'auto', thumbnailHeight: 200

  • Cascading layout
    Sometimes also called masonry layout. This layout is column based. Image aspect ratio is conserved, with no cropping.
    Set the special value 'auto' to thumbnailHeight


    thumbnailWidth: 300, thumbnailHeight: 'auto'

  • More about gallery layout
    The gallery layout can be tuned with more settings:
    - Thumbnail border size: thumbnailBorderHorizontal, thumbnailBorderVertical
    - Gutter space between thumbnails: thumbnailGutterWidth, thumbnailGutterHeight
    - Thumbnail alignement is configured with the option thumbnailAlignment.

Launching the gallery

Settings are passed to the script on initialization, and are CaSe sEnSiTiVe:

HTML markup example:

use the data-nanogallery2 attribute.

<div data-nanogallery2 = '{
    <!-- ### gallery settings ### -->
    "thumbnailHeight":  150,
    "thumbnailWidth":   150,
    "itemsBaseURL":     ""

  <!-- ### gallery content ### -->
  <a href="img_01.jpg" data-ngthumb="img_01t.jpg">Title Image 1</a>
  <a href="img_02.jpg" data-ngthumb="img_02t.jpg">Title Image 2</a>
  <a href="img_03.jpg" data-ngthumb="img_03t.jpg">Title Image 3</a>
with markup, options must respect the JSON format (and not the javascript object syntax). Property names and string values must be between double-quotes ".

Javascript example:

settings are passed to the nanogallery2() function.

  <!-- ### gallery settings ### -->
  thumbnailHeight:  150,
  thumbnailWidth:   150,
  itemsBaseURL:     '',

  <!-- ### gallery content ### -->
  items: [
      { src: 'img_01.jpg', srct: 'img_01t.jpg', title: 'Title Image 1' },
      { src: 'img_02.jpg', srct: 'img_02t.jpg', title: 'Title Image 2' },
      { src: 'img_03.jpg', srct: 'img_03t.jpg', title: 'Title Image 3' }

You may also use the visual BUILDER to quickly test some of the available options.

Gesture and touch actions

Standard gesture actions are supported to control the gallery and the lightbox.

1. Gallery touch actions

Open image in lightbox
Tap twice

The hover animation is fired on first tap.
Image is displayed in lightbox on second one.
This is the default behaviour.

Single tap

The hover animation is fired on tap, and after a defined delay, the image is automatically displayed in the lightbox.
Use the option touchAutoOpenDelay to enable this behaviour.
Switch to next/previous page

Horizontal swipe

Switch to next/previous gallery page, when option galleryDisplayMode: 'pagination'

2. Lightbox touch actions

Switch to another image

Horizontal swipe

Tap left/right image side


Double tap

Pan image
Close lightbox

Swipe down

UI interactions

nanogallery2 includes UI interactions and animations to capture the attention of your visitors.

1. Gallery display animations

Use the option galleryDisplayTransition to define the animation for displaying the gallery.

Possible values: none, slideUp, rotateX.
The duration of the animation is defined with galleryDisplayTransitionDuration.

2. Thumbnail display animations

The display of each individual thumbnail can be animated with the option thumbnailDisplayTransition.

Possible values: none, slideUp, slideDown, scaleUp, scaleDown, fadeIn, randomScale, flipDown, flipUp, slideDown2, slideUp2, slideRight, slideLeft, custom.
Duration is defined in ms, with the option thumbnailDisplayTransitionDuration, and delay between the display of 2 thumbnails is configured with thumbnailDisplayInterval.

3. Thumbnail touch and hover effects

These animations are fired on mouse hover or when the user touch the thumbnail. Multiple animations can be combined.

They are configured with the option thumbnailHoverEffect2: 'effect1|effect2|...'
Where effect is :
  • A predefined preset, like:
    - 'imageGrayOn': to animate image from color to black&white
    - 'scale120': to upscale the thumbnail by 20%
    - 'borderLighter': to make the border color lighter

    Example: thumbnailHoverEffect2: 'imageGrayOn|scale120'

    See here for the list of available presets.

  • Or a customized animation:
    In this case, the syntax of the effect is [element]_[property]_[fromValue]_[toValue]
    - Rotate the image from 0 to 15 degre: 'image_rotateZ_0deg_15deg'
    - Upscale the image: 'image_scale_1.00_1.20'

    To combine both effects: 'image_rotateZ_0deg_15deg|image_scale_1.00_1.20'

    See here for more details.

Additional effect tuning is also available for controling duration, easing, hover out effect, sequential animation, etc.
See the tuning section.

Reference guide


Configure the behaviour of the gallery.
property type default description min
thumbnailOpenImage boolean true Gallery with or without lightbox.
  • true: lightbox is enabled
  • false: lightbox is disabled. No image will be displayed when a thumbnail is clicked/touched.
galleryDisplayMode string 'fullContent' Define the elements to display.

Possible values:
  • 'fullContent': display all thumbnails at once
  • 'moreButton': display N rows and a button to show N more rows (see galleryDisplayMoreStep)
  • 'pagination': display N rows and numbers/dots to paginate the gallery (see galleryMaxRows)
  • 'rows': display maximum N rows (see galleryMaxRows). The number of remaining images is displayed over the last thumbnail.
galleryDisplayMoreStep integer 2 Set the number of rows to display each time the "more button" is hit.

only for galleryDisplayMode: 'moreButton'
galleryPaginationMode string 'rectangles' Display type in pagination mode (galleryDisplayMode: 'pagination').
Possible values:
  • 'rectangles'
  • 'dots'
  • 'numbers'
galleryMaxRows integer 2 Maximum number of rows to display

Only for galleryDisplayMode: 'rows' or galleryDisplayMode: 'pagination'.

Not supported if thumbnailHeight: 'auto'
paginationVisiblePages integer 10 Maximum number of pagination items displayed

only for galleryDisplayMode: 'pagination' and galleryPaginationMode: 'numbers'
paginationSwipe boolean true Enables swipe gesture to display next/previous gallery page. 1.0
galleryLastRowFull boolean false When enabled, the last thumbnail's row will not be displayed if it doesn't fill the full width.

Only for grid and justified layouts.
gallerySorting string '' Sort order. No sorting by default.
Possible values: 'titleAsc', 'titleDesc', 'reversed', 'random' (=shuffle).
galleryMaxItems integer 0 Maximum number of items per album. 0 = display all. 1.0
galleryResizeAnimation boolean true Animate the moving of thumbnails to their new position when the gallery is resized. 1.0
'dark' Gallery theme (thumbnails, navigation...).
Possible values: 'dark', 'light'
Custom themes are supported.

since v1.5, properties 'colorScheme' and 'galleryTheme' are synonymous
openOnStart string Opens the specified album or display the specified image on library start.
Syntax: 'albumID' or 'albumID/imageID'
thumbnailSelectable boolean false Enable/disable the selection mode. A checkbox is displayed over each thumbnail to allow the user to select multiple thumbnails. 1.0
galleryRenderDelay integer 60 Delay in ms before starting the gallery rendering. 1.3
thumbnailDisplayOutsideScreen boolean false Display or hide thumbnails which are displayed outside of the screen (display may impact performances) 1.2
galleryDisplayTransition string 'none' Transition for displaing the gallery. Applied on the whole gallery.
Possible values: 'none', 'rotateX', 'slideUp'
galleryDisplayTransitionDuration integer 1000 Duration of the gallery display transition, in milliseconds. 1.4


Configure the layout and the content of the thumbnails.

property type default description min
thumbnailWidth integer
Thumbnails image width in pixels, or 'auto'.
Use 'auto' for justified layout.
thumbnailHeight integer
Thumbnails image height in pixels, or 'auto'.
Use 'auto' for cascading/masonry layout.
thumbnailAlignment string 'fillWidth' Horizontal thumbnail alignement in the available space width.
This option is ignored for the justified layout.

Possible values:
  • 'left'

  • 'right'

  • 'center'

  • 'justified'

    Note: the parameter thumbnailGutterWidth is ignored.

  • 'fillWidth' (v2.0+)

    The thumbnails are downscaled to use all the available width.
thumbnailGutterWidth integer 2 Sets the horizontal gutter space between thumbnails. 1.0
thumbnailGutterHeight integer 2 Sets the vertical gutter space between thumbnails. 1.0
thumbnailBorderHorizontal integer 2 Set the left and right thumbnail border size. 1.0
thumbnailBorderVertical integer 2 Set the top and bottom thumbnail border size. 1.0
thumbnailFeaturedKeyword string '*featured' Keyword to set the feature status of a thumbnail. The keyword is searched in the title and the description.
If the keyword is found, the featured icon will be displayed over the thumbnail.
thumbnailDisplayInterval integer 15 Interval in ms between the display of 2 thumbnails. 1.0
thumbnailDisplayTransition string 'fadeIn' Transition used to display each thumbnail.

Possible values: 'slideUp', 'slideDown', 'scaleUp', 'scaleDown', 'fadeIn', 'randomScale', 'flipDown', 'flipUp', 'slideDown2', 'slideUp2', 'slideRight', 'slideLeft', 'custom'

Note: some values support the syntax TRANISITION_VAL_EASING
- TRANISITION: the name of the display transition
- VAL: a start value for the animation
- EASING: transition easing formula name (optional)

Example: scaleDown_2_bounce

List of values supporting the extended syntax:
- scaleDown: VAL is the start scale factor (default is 1.3)
- scaleUp: VAL is the start scale factor (default is 0.6)
- flipDown: VAL is the start distance in pixel (default is -100)
- flipUp: VAL is the start distance in pixel (default is 100)
- slideDown: VAL is the start distance in pixel (default is -50)
- slideUp: VAL is the start distance in pixel (default is 50)
- slideDown2: VAL is the start distance in pixel (default is -100)
- slideUp2: VAL is the start distance in pixel (default is 100)
- slideRight: VAL is the start distance in pixel (default is -150)
- slideLeft: VAL is the start distance in pixel (default is 150)
thumbnailDisplayTransitionDuration integer 240 Duration of the display transition. 1.0
thumbnailStacks integer 0 Adds N stacks behind each thumbnail. Usefull for thumbnails hover effects 1.2
thumbnailWaitImageLoaded boolean true Waits until thumbails images are fully downloaded before displaying them smoothly. 1.4
thumbnailCrop boolean true If needed, thumbnail image will be cropped to avoid black borders (only for grid layout).
thumbnailLastImgSliderDelay integer 2000 Image slider last displayed thumbnail.
Delay in ms between the display of images.
Set it to 0 to disable it.
Supported in grid layout with galleryDisplayMode set to 'rows' or to 'fullContent' with galleryLastRowFull enabled.
Thumbnail image sizes must be defined.


For a fully responsive gallery, you can define multiple thumbnail sizes for each image.
The used sized is dependant of the screen resolution.
5 screen resolutions are supported: XS (extra-small), SM (small), ME (medium), LA (large), XL (extra-large)
  • Use the following syntax to assign multiple values to thumbnailWidth:
    'defaultWidth XSw1 SMw2 MEw3 LAw4 XLw5' where w1 to w5 are the thumbnails widths for resolutions XS to XL.
  • and for thumbnailHeight
    'defaultHeight XSh1 SMh2 MEh3 LAh4 XLh5' where h1 to h5 are the heights for resolutions XS to XL.
  • Not all values are mandatory. The default value will be used if a value is missing.
  • The value auto is supported.

  • Grid layout:
    thumbnailWidth: '300 XS100 LA400 XL500', thumbnailHeight: '200 XS80 LA250 XL350'
  • Grid and justified layout depending on the resolution:
    thumbnailWidth: 'auto XS80 SM120', thumbnailHeight: '200 XS80 SM120'
  • Justified and cascading layout depending on the resolution:
    thumbnailWidth: 'auto XS80 SM120', thumbnailHeight: '200 XSauto SMauto'


The label is composed by a title and a description. Set these settings to the thumbnailLabel parameter.


        thumbnailHeight: 200,
        thumbnailWidth: 300,
        thumbnailAlignment: 'center',
        thumbnailLabel: { position: 'overImageOnBottom', hideIcons: true },

property type default description min
position string 'overImageOnBottom' Position of the label on the thumbnail.
Possible values: 'overImageOnBottom', 'overImageOnTop', 'overImageOnMiddle', 'onBottom'

align string 'center' Horizontal text alignment.
Possible values: 'right', 'center', 'left'
display boolean true Displays or hides the label (title and description). 1.0
displayDescription boolean false Displays or hides the description. 1.0
hideIcons boolean true Hides or displays the icons beside the title. 1.0
titleMaxLength integer 0 Title maximum length to display. 1.0
titleMultiLine boolean false Title can be multiline (not supported with position:'onBottom'). 1.0
title string Variable to set the image title (undescores are replaced by spaces).
Possible values:
- '%filename': use the filemanme without path
- '%filenameNoExt': use the filemanme without path and without extension
titleFontSize string Set the title font size.
Example: titleFontSize: '2em'
descriptionMaxLength integer 0 Description maximum length to display. 1.0
descriptionMultiLine boolean false Description can be multiline (not supported with position:'onBottom'). 1.0
descriptionFontSize string Set the description font size.
Example: descriptionFontSize: '0.8em'


Hover effects are triggered on mouse over or on touch-tap. They are confugured with the thumbnailHoverEffect2 parameter.


You can set one or multiple presets to the thumbnailHoverEffect2 with the syntax thumbnailHoverEffect2: 'preset1|preset2|...'

Possible presets:

  • Effect on image: 'imageBlurOn', 'imageBlurOff', 'imageGrayOn', 'imageGrayOff', imageSepiaOn', 'imageSepiaOff', 'imageScale150', 'imageScaleIn80', 'imageScale150Outside', 'imageSlideUp', 'imageSlideDown', 'imageSlideRight', 'imageSlideLeft'
  • Effect on tools: 'toolsAppear', 'toolsSlideDown', 'toolsSlideUp'
  • Effect on label: 'labelAppear', 'labelAppear75', 'labelOpacity50', 'scaleLabelOverImage', 'descriptionAppear', 'labelSlideUpTop', 'labelSlideUp', 'labelSlideDown', 'descriptionSlideUp'
  • Effect on whole thumbnail: 'scale120'
  • Effect on thumbnail border: 'borderLighter', 'borderDarker'
  • Misc: 'overScale', 'overScaleOutside', 'slideUp', 'slideDown', 'slideRight', 'slideLeft'

Usage example: thumbnailHoverEffect2: 'borderDarker|labelAppear75'

Advanced usage

For a full control of the effects, use the syntax thumbnailHoverEffect2: 'effect1|effect2|...'

where effectN has the syntax [element]_[property]_[fromValue]_[toValue]

  • [element]: element to apply the transformation.
    Possible values: thumbnail, image, label, description, title, tools, customlayer
  • [property]:
    • any CSS property to apply the animation value
      Example: label_backgroundColor_rgba(255,255,255,0.80)_rgba(255,255,255,0.01)
    • for CSS transform property, just use the transform-function.
      Limited to: translateX, translateY, rotateX, rotateY, rotateZ, scale
      Example: image_rotateZ_0deg_15deg
    • for CSS filters, just use the visual effect.
      Limited to: blur, brightness, grayscale, sepia, contrast, opacity, saturate
      Example: 'image_grayscale_0%_100%
  • [fromValue]: initial value
  • [toValue]: value at the end of the transformation

Live example on codepen: demo - advanced thumbnail hover effect

Some examples:

  • One hover effect:
    • Remove the sepia filter on the image: thumbnailHoverEffect2: 'image_sepia_100%_1%'
    • Apply a blur filter on the image: 'image_blur_0.00px_2.00px'
    • Rotate the image from 0degre to 15degre: 'image_rotateZ_0deg_15deg'
    • Apply a grayscale filter the image: 'image_grayscale_0%_100%'
    • Zoom the image in: image_scale_1.00_1.20
    • Zoom the image out: image_scale_1.20_1.00
    • Change the transparency of label background: 'label_backgroundColor_rgba(255,255,255,0.80)_rgba(255,255,255,0.01)'
    • Apply a red colorization on the image: customlayer_backgroundColor_rgba(160,0,0,0.0)_rgba(160,0,0,0.5)
    • Change the transparency of the icons: tools_opacity_1_0.5
    • Change the image contrast: image_contrast_1_4
    • Change the image brightness: image_brightness_1_2
  • Two hover effects:
    • Apply a grayscale filter and rotate the image: thumbnailHoverEffect2:'image_grayscale_0%_100%|image_rotateZ_0deg_15deg'

Initialization In some case, it's interesting to set CSS properties but without any animation.
For this, use the option thumbnailBuildInit2: : 'init1|init2|...' where initN has the syntax: [element]_[property]_[Value].
Example : thumbnailBuildInit2: 'image_scale_1.20'

Additional tuning

Fine tuning settings: duration, delay, easing, back duration, back delay, beack easing, hoverin, hoverout, first keyframe

    thumbnailHoverEffect2: { 
      name:           '[effectName]',
      delay:          0,
      duration:       400,
      easing:         'easeOutQuart',
      delayBack:      0,
      durationBack:   300,
      easingBack:     'easeOutQuart',
      hoverin:        true,
      hoverout:       true,
      firstKeyframe:  true

  • duration: the duration of the effect in ms
  • delay: the delay in ms before the transformation is started
  • easing: specify the rate of change of the transformation over time (see
    • Possible values:
      easeInQuad, easeOutQuad, easeInOutQuad, easeInCubic, easeOutCubic, easeInOutCubic, easeInQuart, easeOutQuart, easeInOutQuart, easeInQuint, easeOutQuint, easeInOutQuint, easeInSine, easeOutSine, easeInOutSine, easeInExpo, easeOutExpo, easeInOutExpo, easeInCirc, easeOutCirc, easeInOutCirc, easeOutBounce, easeInBack, easeOutBack, easeInOutBack, elastic, bounce
  • durationBack: duration of the effect to initial state, in ms
  • delayBack: start delay back transformation in ms
  • easingBack: easing used for the back transformation
  • hoverin: used on hover in
  • hoverout: used on hover out
  • firstKeyframe: used for chained animations
Note: name is the only mandatory proprety.
Some examples:
  • thumbnailHoverEffect2: { name: 'imageBlurOn', duration: 800, easing: 'easeInCubic', delayBack: 0, durationBack: 300, easingBack: 'easeOutQuart' }
  • thumbnailHoverEffect2: { name: 'image_rotateZ_0deg_15deg', duration: 800, durationBack: 500}
  • combination of 2 effects:
    thumbnailHoverEffect2: [{ name: 'image_scale_1.00_1.20', duration: 500}, { name: 'image_rotateZ_0deg_15deg', delay: 500}]


Stacks can be added behind thumbnails to create nice hover effects. Their color is defined in the galleryTheme.
Use thumbnailStacks and thumbnailL1Stacks to define then number of stacks.

The thumbnail animation is applied to the stack, but with a percent value.
For example, if thumbnailStacksRotateX is set to 0.4, then the 1st stack will have a percent of 0.6 applied to the rotationX value of the thumbnail.

For the second stack, the percent will be 0.2, for the third one it will be -0,2, and so on.

Possible parameters to set these percents: 'thumbnailStacksTranslateX', 'thumbnailStacksTranslateY', 'thumbnailStacksTranslateZ', 'thumbnailStacksRotateX', 'thumbnailStacksRotateY', 'thumbnailStacksRotateZ', 'thumbnailStacksScale'


Each corner of one thumbnail has a toolbar. You can customize each of these toolbars. Customization is specific for albums and for images.

property type default description min
thumbnailToolbarImage object Image toolbars
Syntax: thumbnailToolbarImage: { topLeft:'', topRight: '', bottomLeft: '', bottomRight: ''}
Possible tools: 'select', 'share', 'featured', 'download', 'cart', 'info'

thumbnailToolbarImage : { topLeft: 'select', topRight : 'featured' }
thumbnailToolbarAlbum object Album toolbars
Syntax: thumbnailToolbarAlbum: { topLeft:'', topRight: '', bottomLeft: '', bottomRight: ''}
Possible tools: 'select', 'share', 'counter', 'counter2', 'cart'

thumbnailToolbarAlbum : { topLeft: 'select', topRight : 'counter' }


Configure how the user can navigate in albums, filter the thumbnails based on tags, and the touch/tap handling.

property type default description min
displayBreadcrumb boolean true Display the breadcrumb for navigation in albums. 1.0
breadcrumbOnlyCurrentLevel boolean true Display only the name of the current album. 1.0
breadcrumbAutoHideTopLevel boolean true No breadcrumb on albums first navigation level. 1.0
breadcrumbHideIcons true Hide or display breadcrumb's icons. 1.0
galleryFilterTags boolean
false Display tags to filter the thumbnails.
Possible values:
- false: disabled
- true: enabled
- 'title': extract the tags from the title (string starting with @)
- 'description': extract the tags from the description (string starting with @)
thumbnailLevelUp boolean false Display one thumbnail to navigate in the parent album. 1.0
locationHash boolean true Enables hash tracking.
This will activate browser Back/Forward navigation (browser history support) and Deep Linking of images and photo albums.
Must be enabled to allow sharing of images/albums.
Note: only one gallery per HTML page should use this feature.
touchAnimation boolean true Enables thumbnail hover animation on touch event.
The user must tap a thumbnail twice to show the image or open a album.
touchAutoOpenDelay integer 0 When a user touch a thumbnail, delay in ms before opening the touched thumbnail.
Particular values:
-1= disabled (user needs to tap twice to open the thumbnail),
0= automatic (the library will calculate automatically the delay).
Note: the parameter is ignored when touchAnimation=false.
navigationFontSize string Define the font size for the navigation (breadcrumb and filters).
Example: navigationFontSize: '1.2em'


Settings can be defined specificaly for the first album level (root level) and for the other ones.
Default settings are used for all album levels (including the first one).
To use a grid layout for the first level, and a justified layout for all other levels
thumbnailHeight: 200, thumbnailWidth: 'auto',
thumbnailL1Height: 300, thumbnailL1Width: 300

view demo on codepen
property min
thumbnailL1Height, thumbnailL1Width 1.0
thumbnailL1Crop 1.0
thumbnailL1Label 1.0
thumbnailL1HoverEffect2 1.0
galleryL1DisplayMode 1.0
galleryL1MaxRows 1.0
galleryL1LastRowFull 1.0
galleryL1FilterTags 1.0
galleryL1MaxItems 1.0
galleryL1Sorting 1.0
thumbnailL1Stacks 1.2
thumbnailL1GutterWidth, thumbnailL1GutterHeight 1.2
thumbnailL1DisplayTransition 1.3
thumbnailL1DisplayTransitionDuration 1.3
thumbnailL1DisplayInterval 1.3
galleryDisplayTransition 1.4
galleryDisplayTransitionDuration 1.4


The lightbox is used to display images in full size.

All available tools can be displaued in each of the 3 toolbar.
Possible tools: 'previousButton', 'pageCounter', 'nextButton', 'playPauseButton', 'fullscreenButton', 'infoButton', 'linkOriginalButton', 'closeButton', 'downloadButton', 'label', 'customN'
To add custom elements in a toolbar, use the label customN, where N is an integer (e.g. custom1, custom2...).
property type default description min
imageTransition string 'swipe' Animation from one image to the next one.
Possible values: 'slideAppear', 'swipe'.
slideshowAutoStart boolean false Starts automatically the slideshow when an image is displayed. 1.0
slideshowDelay integer 3000 Duration of the photo display in slideshow mode (in ms). 1.0
viewerHideToolsDelay integre 3000 Delay of inactivity before hidding the tools and labels. 1.3
viewerFullscreen boolean false Displays images in fullscreen (on supported browser). 1.0
viewerToolbar object Display options for the light main toolbar. 1.0
      viewerToolbar.display boolean true Displays/hides the main toolbar. 1.0
      viewerToolbar.position string 'bottomOverImage' Vertical position.
Possible values: 'top', 'topOverImage', 'bottom', 'bottomOverImage'
      viewerToolbar.align string 'center' Horizontal alignement.
Possible values: 'left', 'right', 'center'
      viewerToolbar.fullWidth boolean false Toolbar is as width as the screen. 1.0
      viewerToolbar.autoMinimize integer 800 Breakpoint for switching between minimized and standard toolbar.
If the width is lower than this value, the toolbar is switched to minimized.
      viewerToolbar.standard string List of items to display in the standard toolbar (comma separated).
For this toolbar, 'minimizeButton' is additionally available.
Default value:
viewerToolbar: { standard :'minimizeButton, label'}
      viewerToolbar.minimized string List of items to display in the minimized toolbar (comma separated).
For this toolbar, 'minimizeButton' is additionally available.
Default value:
viewerToolbar: { standard :'minimizeButton, label, infoButton, shareButton, downloadButton, linkOriginalButton, fullscreenButton'}
viewerTools object Tools positionned in the corners. 1.0
      viewerTools.topLeft string Toolbar positioned in the top left corner.
Default value:
viewerTools : { topLeft: 'pageCounter, playPauseButton'}
      viewerTools.topRight string Toolbar positioned in the top right corner.
Default value:
viewerTools : { topRight: 'zoomButton, closeButton'}
'dark' Image display theme.
Possible values: 'dark', 'light', 'border'.
Custom themes are supported.

since v1.5, properties 'colorSchemeViewer' and 'viewerTheme' are synonymous
viewerDisplayLogo boolean false To display a logo over the image. 1.0
viewerImageDisplay string Manage the image display zoom factor.

Possible values:
  - '': no not apply any zoom factor
  - 'bestImageQuality': display images smaller for a better quality (on high DPI screens like Retina, etc.)
  - 'upscale': upscale image to screen size


All icons used in the gallery can be customized. By default, an icon font is used.
Example: replace the default album icon with a red one from Font Awesome:
     icons.thumbnailAlbum: '<i style="color:#e00;" class="fa fa-search-plus"></i>'
property type default description min
icons.thumbnailAlbum string '<i class="nGY2Icon icon-folder-empty"></i>' Thumbnail album icon 1.0
icons.thumbnailImage string '<i class="nGY2Icon icon-picture"></i>' Thumbnail image icon 1.0
icons.breadcrumbAlbum string '<i class="nGY2Icon icon-folder-empty"></i>' Breadcrum album icon 1.0
icons.breadcrumbHome string '<i class="nGY2Icon icon-home"></i>' Breadcrumb home icon 1.0
icons.breadcrumbSeparator string '<i class="nGY2Icon icon-left-open"></i>' Breadcrumb separator icon 1.0
icons.breadcrumbSeparatorRtl string '<i class="nGY2Icon icon-right-open"></i>' Breadcrumb separator RTL icon 1.0
icons.navigationFilterSelected string '<i style="color:#bff;" class="nGY2Icon icon-toggle-on"></i>' Navigation - thumbnail filter - selected icon 1.0
icons.navigationFilterUnselected string '<i class="nGY2Icon icon-toggle-off"></i>' Navigation - thumbnail filter - unselected icon 1.0
icons.navigationFilterSelectedAll string '<i class="nGY2Icon icon-toggle-off"></i>' Navigation - thumbnail filter - unselect all icon 1.0
icons.thumbnailSelected string '<i class="nGY2Icon icon-ok-circled"></i>' Thumbnail selection - selected icon 1.0
icons.thumbnailUnselected string '<i class="nGY2Icon icon-circle-empty"></i>' Thumbnail selection - unselected icon 1.0
icons.thumbnailFeatured string '<i style="color:#ffa;" class="nGY2Icon icon-star"></i>' Thumbnail - featured icon 1.0
icons.thumbnailCounter string '<i class="nGY2Icon icon-picture"></i>' Thumbnail - image icon 1.0
icons.thumbnailShare string '<i class="nGY2Icon icon-share"></i>' Thumbnail - share icon 1.0
icons.thumbnailDownload string '<i class="nGY2Icon icon-download"></i>' Thumbnail - download icon 1.0
icons.thumbnailInfo string '<i class="nGY2Icon icon-ngy2_info2"></i>' Thumbnail - info icon 1.0
icons.thumbnailCart string '<i class="nGY2Icon icon-basket"></i>' Thumbnail - add to shopping cart icon 1.0
icons.thumbnailDisplay string '<i class="nGY2Icon icon-ngy2_zoom_in2"></i>' Thumbnail - display image icon 1.0
icons.thumbnailCustomTool[1..10] string 'T1..T10' Thumbnail - custom tool 1 to 10 1.1
icons.thumbnailAlbumUp string '<i style="font-size: 3em;" class="nGY2Icon icon-level-up"></i>' Thumbnail navigation - album up icon 1.0
icons.paginationNext string '<i class="nGY2Icon icon-right-open"></i>' Gallery pagination - next page icon 1.0
icons.paginationPrevious string '<i class="nGY2Icon icon-left-open"></i>' Gallery pagination - previous page icon 1.0
icons.galleryMoreButton string '<i class="nGY2Icon icon-picture"></i>   <i class="nGY2Icon icon-right-open"></i>' close button icon 1.0
icons.buttonClose string '<i class="nGY2Icon icon-ngy2_close2"></i>' close button icon 1.0
icons.viewerPrevious string '<i class="nGY2Icon icon-ngy2_chevron-left"></i>' Lightbox - icon for previous image (toolbar) 1.0
icons.viewerNext string '<i class="nGY2Icon icon-ngy2_chevron-right"></i>' Lightbox - icon for next image (toolbar) 1.0
icons.viewerImgPrevious string '<i class="nGY2Icon icon-ngy2_chevron_left3"></i>' Lightbox - icon for previous image (on the left side of the image) 1.0
icons.viewerImgNext string '<i class="nGY2Icon icon-ngy2_chevron_right3"></i>' Lightbox - icon for next image (on the right side of the image) 1.0
icons.viewerDownload string '<i class="nGY2Icon icon-ngy2_download2"></i>' Lightbox - icon image download (toolbar) 1.0
icons.viewerToolbarMin string '<i class="nGY2Icon icon-ellipsis-vert"></i>' Lightbox - icon for minimized toolbar 1.0
icons.viewerToolbarStd string '<i class="nGY2Icon icon-menu"></i>' Lightbox - icon for maximized toolbar 1.0
icons.viewerPlay string '<i class="nGY2Icon icon-play"></i>' Lightbox - icon play - to start the slideshow (toolbar) 1.0
icons.viewerPause string '<i class="nGY2Icon icon-pause"></i>' Lightbox - icon pause - to stop the slideshow (toolbar) 1.0
icons.viewerFullscreenOn string '<i class="nGY2Icon icon-resize-full"></i>' Lightbox - icon to switch on fullscreen (toolbar) 1.0
icons.viewerFullscreenOff string '<i class="nGY2Icon icon-resize-small"></i>' Lightbox - icon to switch off fullscreen (toolbar) 1.0
icons.viewerZoomIn string '<i class="nGY2Icon icon-ngy2_zoom_in2"></i>' Lightbox - icon zoom in (toolbar) 1.0
icons.viewerZoomOut string '<i class="nGY2Icon icon-ngy2_zoom_out2"></i>' Lightbox - icon zoom out (toolbar) 1.0
icons.viewerLinkOriginal string '<i class="nGY2Icon icon-ngy2_external2"></i>' Lightbox - icon link to original image (toolbar) 1.0
icons.viewerInfo string '<i class="nGY2Icon icon-ngy2_info2"></i>' Lightbox - icon infobox (toolbar) 1.0
icons.viewerShare string '<i class="nGY2Icon icon-ngy2_share2"></i>' Lightbox - icon share link (toolbar) 1.0
icons.user string '<i class="nGY2Icon icon-user"></i>' Lightbox - icon author (infobox) 1.0
icons.location string '<i class="nGY2Icon icon-location"></i>' Lightbox - icon location on Google Maps (infobox) 1.0
icons.config string '<i class="nGY2Icon icon-wrench"></i>' Lightbox - icon config for EXIF (infobox) 1.0
icons.viewerCustomTool[1..10] string 'T1..T10' Lightbox - custom tool 1 to 10 1.1
icons.shareFacebook string '<i style="color:#3b5998;" class="nGY2Icon icon-facebook-squared"></i>' Lightbox - icon Facebook (share popup) 1.0
icons.shareTwitter string '<i style="color:#00aced;" class="nGY2Icon icon-twitter-squared"></i>' Lightbox - icon Twitter (share popup) 1.0
icons.shareGooglePlus string '<i style="color:#dd4b39;" class="nGY2Icon icon-gplus-squared"></i>' Lightbox - icon Google plus (share popup) 1.0
icons.shareTumblr string '<i style="color:#32506d;" class="nGY2Icon icon-tumblr-squared"></i>' Lightbox - icon Tumblr (share popup) 1.0
icons.sharePinterest string '<i style="color:#cb2027;" class="nGY2Icon icon-pinterest-squared"></i>' Lightbox - icon Pinterest (share popup) 1.0
icons.shareVK string '<i style="color:#3b5998;" class="nGY2Icon icon-vkontakte"></i>' Lightbox - icon Pinterest (share popup) 1.3
icons.shareMail string '<i style="color:#555;" class="nGY2Icon icon-mail-alt"></i>' Lightbox - icon mail-to (share popup) 1.0


Themes allow you to customize some elements without changing the CSS file.
Two separated themes can be set: one for the gallery (galleryTheme), and one for the lightbox (viewerTheme).
For each one, 2 templates can be used: dark (default valude) and light. You can define your own customized theme.

To change the background and the boder color of the thumbnails
1. define one theme: var myCS= { thumbnail : { background: '#F00', borderColor: '#F00' } };
2. assign it to the gallery: galleryTheme: myCS

Gallery theme format (with default values):

  navigationBar:        { background: 'none', borderTop: '', borderBottom: '', borderRight: '', borderLeft: '' },
  navigationBreadcrumb: { background: '#111', color: '#fff', colorHover: '#ccc', borderRadius: '6px' },
  navigationFilter :    { color: '#ddd', background: '#111', colorSelected: '#fff', backgroundSelected: '#111', borderRadius: '6px' },
  thumbnail:            { background: '#444', backgroundImage: 'linear-gradient(315deg, #111 0%, #557 90%)', borderColor: '#000', labelOpacity : 1, labelBackground: 'rgba(34, 34, 34, 0)', titleColor: '#eee', titleBgColor: 'transparent', titleShadow: '', descriptionColor: '#ccc', descriptionBgColor: 'transparent', descriptionShadow: '', stackBackground: '#aaa' },
  thumbnailIcon:        { padding: '5px', color: '#fff' },
  pagination:           { background: '#111', backgroundSelected: '#666', color: '#fff', borderRadius: '2px', shapeBorder: '3px solid #666', shapeColor: '#444', shapeSelectedColor: '#aaa'}

Lightbox theme format (with default values):

  background:     '#000', imageBorder: 'none', imageBoxShadow: 'none',
  barBackground:  'rgba(4, 4, 4, 0.7)', barBorder: '0px solid #111', barColor: '#eee', barDescriptionColor: '#aaa'


nanogallery2 comes with an interesting set of new features that should streamline your development experience.

Due to many enhancements, nanogallery2 is not 100% compatible with nanoGALLERY.
In particular, the thumbnail hover effects engine has been rewritten: the option thumbnailHoverEffect is now replaced by thumbnailHoverEffect2.
Here's the list of depreciated and no more supported options.
property comment
thumbnailHoverEffect replaced by thumbnailHoverEffect2
picasaUseUrlCrossDomain no more needed
albumList replaced by albumList2
galleryToolbarHideIcons Replaced by breadcrumbHideIcons. Each icon can now be customized with the icons option.
thumbnail selection is now managed by the thumbnailSelectable option.
paginationMaxLinesPerPage replaced by galleryMaxRows and galleryL1MaxRows
paginationDots replaced by galleryPaginationMode
albumMax replaced by galleryMaxItems and galleryL1MaxItems - ignored for self hosted images.
replaced by gallerySorting and galleryL1Sorting
managed automatically
thumbnailAdjustLastRowHeight is now the standard behaviour
fnChangeSelectMode use fnThumbnailSelection instead.
use itemsSetSelectedValue instead.
getSelectedItems use itemsSelectedGet instead.
callbacks comment
fnViewerInfo No more used. Please replace with toolbar custom buttons (fnImgToolbarCustInit, fnImgToolbarCustClick)
fnInitGallery replaced and enhanced by fnGalleryRenderStart and fnGalleryRenderEnd
API methods comment
getItems Instead, use data to get a pointer to an array containing all the items.
Example: $('#your_nanogallery2').nanogallery2('data').items;
getItem replaced by: $('#your_nanogallery2').nanogallery2('data').items[item_index];
getItemsIndex no more needed
refreshSize refresh


Recommandations / Performances / FAQ

Thumbnails hover effects:

  • do not combine too much effects (smooth animation on a computer may be slow on a mobile device).
Self hosted images:
  • define each thumbnail's size.
  • define each image's size.
Social sharing
  • Assign an ID to the DIV containing the gallery.
  • Each album and image must have an ID defined.
  • IDs should never been changed.


By default, HTML tags cannot be used in titles and descriptions of images.
To enable HTML tags, set the option allowHTMLinData: true.
Be aware that this could lead to XSS (cross site scripting) vulnerability.


Firefox 6+ - Chrome 16+ - Edge 13+ - IE 10+ - Opera 12.1+ - Yandex 14.12+ - iPhone 5+ / iOS 6+ - Safari 6.2+
(some features may not be available on every platform).

Testing services provided by BrowserStackbrowserstack