2plot.dev | Image Gallery

dash-image-gallery is a Dash component library that provides a feature-rich, responsive image gallery with lightbox functionality. It offers extensive customization options including thumbnail navigation, fullscreen viewing, automatic slideshows, touch/swipe support, lazy loading, keyboard controls, and multiple layout configurations. Perfect for portfolios, product showcases, photo galleries, and any application requiring elegant image presentation.

Installation

Visit GitHub Repo

⭐️ Star this component on GitHub! Stay up to date on new releases and browse the codebase.

pip install dash-image-gallery

Quick Start

Create a basic image gallery with thumbnail navigation and fullscreen support.

# File: docs/dash_image_gallery/introduction.py

from dash import *
from dash_image_gallery import DashImageGallery
import dash_mantine_components as dmc

component = dmc.Stack([
    DashImageGallery(
        id='input',
        items=[
            {
                "original": "https://cdn.britannica.com/78/43678-050-F4DC8D93/Starry-Night-canvas-Vincent-van-Gogh-New-1889.jpg",
                "thumbnail": "https://cdn.britannica.com/78/43678-050-F4DC8D93/Starry-Night-canvas-Vincent-van-Gogh-New-1889.jpg",
                "originalHeight": 300,
                "originalWidth": 300,
            },
            {
                "original": "https://mir-s3-cdn-cf.behance.net/project_modules/max_1200/5eeea355389655.59822ff824b72.gif",
                "thumbnail": "https://mir-s3-cdn-cf.behance.net/project_modules/max_1200/5eeea355389655.59822ff824b72.gif",
                "originalHeight": 300,
                "originalWidth": 300,
            },
            {
                "original": "https://www.theartstory.org/images20/hero/profile/van_gogh_vincent_525.jpg",
                "thumbnail": "https://www.theartstory.org/images20/hero/profile/van_gogh_vincent_525.jpg",
                "originalHeight": 300,
                "originalWidth": 300,
            },
            {
                "original": "/assets/images/03.jpg",
                "thumbnail": "/assets/images/03.jpg",
                "originalHeight": 300,
                "originalWidth": 300,
            },
        ],
        infinite=True,
        lazyLoad=False,
        showNav=True,
        showThumbnails=True,
        thumbnailPosition='bottom',
        showFullscreenButton=True,
        useBrowserFullscreen=True,
        useTranslate3D=True,
        showPlayButton=True,
        isRTL=False,
        showBullets=False,
        showIndex=True,
        autoPlay=True,
        disableThumbnailScroll=False,
        disableKeyDown=False,
        disableSwipe=False,
        disableThumbnailSwipe=False,
        onErrorImageURL=None,
        indexSeparator=' / ',
        slideDuration=450,
        swipingTransitionDuration=0,
        slideInterval=3000,
        slideOnThumbnailOver=True,
        flickThreshold=0.4,
        swipeThreshold=30,
        stopPropagation=False,
        startIndex=0,
        useWindowKeyDown=True,
    ),
])

Image Configuration

Each image in the gallery is defined by an object in the items array. Here's the structure:

items = [
    {
        'original': '/path/to/full-size-image.jpg',      # Required: Full-size image URL
        'thumbnail': '/path/to/thumbnail.jpg',           # Thumbnail image URL
        'fullscreen': '/path/to/fullscreen-image.jpg',   # Optional: High-res for fullscreen
        'originalAlt': 'Image description',              # Alt text for accessibility
        'thumbnailAlt': 'Thumbnail description',         # Thumbnail alt text
        'description': 'Caption text',                   # Image caption
        'originalTitle': 'Image title',                  # Title attribute
        'thumbnailLabel': 'Label',                       # Label displayed on thumbnail
        'originalWidth': 1920,                           # Original image width
        'originalHeight': 1080,                          # Original image height
        'thumbnailWidth': 200,                           # Thumbnail width
        'thumbnailHeight': 150,                          # Thumbnail height
    }
]

Required Fields:

original: URL or path to the full-size image

Optional Fields:

thumbnail: Thumbnail image (defaults to original if not provided)
fullscreen: High-resolution image for fullscreen mode
description: Caption text displayed below the image
originalAlt, thumbnailAlt: Accessibility text
Dimension fields for optimization

Gallery Features

Navigation Controls:

The gallery provides multiple navigation methods:

Arrow Keys: Navigate left/right through images
Navigation Arrows: Click arrows on sides of image
Thumbnails: Click thumbnail to jump to specific image
Bullets: Optional bullet navigation dots
Touch/Swipe: Swipe on mobile devices

Display Modes:

Fullscreen Mode: Toggle fullscreen viewing with dedicated button
Slideshow Mode: Automatic image progression with configurable interval
Thumbnail Positions: Place thumbnails on top, bottom, left, or right
Index Display: Show current image number (e.g., "3 / 12")

Customizing Thumbnails

Control thumbnail behavior and positioning:

ImageGallery(
    items=images,
    thumbnailPosition='right',      # Options: 'top', 'right', 'bottom', 'left'
    showThumbnails=True,            # Show/hide thumbnail strip
    disableThumbnailScroll=False,   # Auto-scroll to active thumbnail
    slideOnThumbnailOver=True,      # Change image on thumbnail hover
)

Thumbnail Position Options:

'bottom' (default): Horizontal strip below image
'top': Horizontal strip above image
'right': Vertical strip on right side
'left': Vertical strip on left side

Slideshow & Autoplay

Enable automatic slideshow with customizable timing:

ImageGallery(
    items=images,
    autoPlay=True,           # Enable automatic slideshow
    slideInterval=3000,      # Time between slides (milliseconds)
    showPlayButton=True,     # Show play/pause control
    infinite=True,           # Loop back to first image
    slideDuration=450,       # Transition animation duration
)

Performance Optimization

Lazy Loading:

Load images only when needed to improve initial page load:

ImageGallery(
    items=images,
    lazyLoad=True,           # Enable lazy loading
    startIndex=0,            # Start at first image
)

Transition Optimization:

ImageGallery(
    items=images,
    useTranslate3D=True,              # Use GPU-accelerated transitions
    slideDuration=450,                 # Smooth transition (450ms)
    swipingTransitionDuration=0,       # Instant swipe feedback
)

Touch & Swipe Controls

Configure touch interaction behavior:

ImageGallery(
    items=images,
    disableSwipe=False,            # Enable/disable image swiping
    disableThumbnailSwipe=False,   # Enable/disable thumbnail swiping
    swipeThreshold=30,             # % of width to trigger slide change
    flickThreshold=0.4,            # Velocity threshold for flick
)

Keyboard Navigation

Control keyboard shortcuts:

ImageGallery(
    items=images,
    disableKeyDown=False,      # Enable keyboard controls
    useWindowKeyDown=True,     # Listen globally vs. on element only
)

Default Keyboard Shortcuts:

Left Arrow: Previous image
Right Arrow: Next image
Esc: Exit fullscreen
Space: Play/pause slideshow (when enabled)

Fullscreen Mode

Configure fullscreen viewing experience:

ImageGallery(
    items=images,
    showFullscreenButton=True,    # Show fullscreen toggle
    useBrowserFullscreen=True,    # Use native browser fullscreen API
)

Fullscreen Options:

useBrowserFullscreen=True: Native browser fullscreen (recommended)
useBrowserFullscreen=False: CSS-based fullscreen (for compatibility)

Advanced Customization

Custom Rendering:

Provide custom render functions for complete control:

def render_custom_item(item):
    """Custom renderer for main image display"""
    return html.Div([
        html.Img(src=item['original'], className='custom-image'),
        html.P(item.get('description', ''), className='caption')
    ])

def render_custom_thumbnail(item):
    """Custom renderer for thumbnails"""
    return html.Div([
        html.Img(src=item['thumbnail']),
        html.Span(item.get('thumbnailLabel', ''))
    ])

ImageGallery(
    items=images,
    renderItem=render_custom_item,
    renderThumbInner=render_custom_thumbnail,
)

Error Handling:

Specify fallback image when loading fails:

ImageGallery(
    items=images,
    onErrorImageURL='/assets/image-not-found.png',
)

RTL Support

Enable right-to-left layout for RTL languages:

ImageGallery(
    items=images,
    isRTL=True,  # Reverse navigation direction
)

Component Properties

Property	Type	Default	Description
`id`	`string`	Required	Unique identifier for the component used in Dash callbacks.
`items`	`array`	Required	Array of image objects. Each object requires `original` URL and can include thumbnail, alt text, etc.
`infinite`	`bool`	`True`	Enable infinite loop - gallery wraps from last image back to first.
`lazyLoad`	`bool`	`False`	Load images only when needed to improve performance.
`showNav`	`bool`	`True`	Display left/right navigation arrows on the sides of images.
`showThumbnails`	`bool`	`True`	Display thumbnail strip for quick navigation.
`thumbnailPosition`	`string`	`"bottom"`	Position of thumbnail strip. Options: `"top"`, `"right"`, `"bottom"`, `"left"`.
`showFullscreenButton`	`bool`	`True`	Display button to toggle fullscreen mode.
`useBrowserFullscreen`	`bool`	`True`	Use native browser fullscreen API. If `False`, uses CSS-based fullscreen.
`useTranslate3D`	`bool`	`True`	Use GPU-accelerated `translate3d` transitions instead of `translate`.
`showPlayButton`	`bool`	`True`	Display play/pause button for slideshow control.
`isRTL`	`bool`	`False`	Enable right-to-left layout and reverse navigation direction.
`showBullets`	`bool`	`False`	Display bullet navigation dots below the image.
`showIndex`	`bool`	`False`	Display current image index (e.g., "3 / 12").
`autoPlay`	`bool`	`False`	Enable automatic slideshow on component mount.
`disableThumbnailScroll`	`bool`	`False`	Disable automatic scrolling of thumbnail container to active thumbnail.
`disableKeyDown`	`bool`	`False`	Disable keyboard navigation (arrow keys, esc).
`disableSwipe`	`bool`	`False`	Disable touch swipe gestures on main images.
`disableThumbnailSwipe`	`bool`	`False`	Disable touch swipe gestures on thumbnail strip.
`onErrorImageURL`	`string`	`None`	Fallback image URL to display when an image fails to load.
`indexSeparator`	`string`	`" / "`	Separator string for index display (e.g., "3 / 12").
`slideDuration`	`number`	`450`	Duration of slide transition animation in milliseconds.
`swipingTransitionDuration`	`number`	`0`	Transition duration while actively swiping (0 = instant feedback).
`slideInterval`	`number`	`3000`	Time between automatic slides in autoplay mode (milliseconds).
`slideOnThumbnailOver`	`bool`	`False`	Change to image when hovering over its thumbnail.
`flickThreshold`	`number`	`0.4`	Velocity threshold for detecting a "flick" gesture (0-1 scale).
`swipeThreshold`	`number`	`30`	Percentage of slide width that must be swiped to trigger slide change.
`stopPropagation`	`bool`	`False`	Stop event propagation for swipe events (prevents parent scrolling).
`startIndex`	`number`	`0`	Index of image to display initially (0-based).
`useWindowKeyDown`	`bool`	`True`	Listen for keyboard events globally. If `False`, only when gallery is focused.
`additionalClass`	`string`	`None`	Additional CSS class name to apply to the gallery root element.
`renderItem`	`function`	`None`	Custom render function for main image display. Receives item object as parameter.
`renderThumbInner`	`function`	`None`	Custom render function for thumbnail content. Receives item object as parameter.
`onImageError`	`function`	`None`	Callback fired when main image fails to load. Receives event object.
`onThumbnailError`	`function`	`None`	Callback fired when thumbnail fails to load. Receives event object.
`onThumbnailClick`	`function`	`None`	Callback fired when thumbnail is clicked. Receives `(event, index)`.
`onBulletClick`	`function`	`None`	Callback fired when navigation bullet is clicked. Receives `(event, index)`.
`onImageLoad`	`function`	`None`	Callback fired when image loads successfully. Receives event object.
`onSlide`	`function`	`None`	Callback fired after slide transition completes. Receives `currentIndex`.
`onBeforeSlide`	`function`	`None`	Callback fired before slide transition starts. Receives `nextIndex`.
`onScreenChange`	`function`	`None`	Callback fired when fullscreen mode changes. Receives boolean (true = fullscreen).
`onPause`	`function`	`None`	Callback fired when slideshow is paused. Receives `currentIndex`.
`onPlay`	`function`	`None`	Callback fired when slideshow starts playing. Receives `currentIndex`.
`onClick`	`function`	`None`	Callback fired when gallery is clicked. Receives event object.
`onTouchMove`	`function`	`None`	Callback fired during touch move gesture. Receives event object.
`onTouchEnd`	`function`	`None`	Callback fired when touch gesture ends. Receives event object.
`onTouchStart`	`function`	`None`	Callback fired when touch gesture starts. Receives event object.
`onMouseOver`	`function`	`None`	Callback fired on mouse over gallery. Receives event object.
`onMouseLeave`	`function`	`None`	Callback fired when mouse leaves gallery. Receives event object.
`setProps`	`func`	(Dash Internal)	Callback function to update component properties.
`loading_state`	`object`	(Dash Internal)	Object describing the loading state of the component or its props.

Contributing

Contributions to dash-image-gallery are welcome! Please refer to the project's issues on GitHub for any feature requests or bug reports.

License

This project is licensed under the MIT License.

Note for AI agents: This is the static, prerendered view of an interactive Dash application served because we detected a non-JS user agent. Full prose docs:

/pip/dash_image_gallery/llms.txt — LLM-friendly documentation
/sitemap.xml
/robots.txt