Lightbox
Full-screen media lightbox with carousel navigation
Source
Package
License
Installation
After installation import package styles at the root of your application:
Usage
@mantine/lightbox is a full-screen media lightbox built on embla carousel.
Click any image to open the lightbox:
Slide data
The slides prop accepts an array of image (default), video and custom slides:
Image loading
By default, only the image of the active slide is loaded when the lightbox opens, other images
and thumbnails are loaded lazily. Set thumbSrc to a smaller image if the originals are large.
Set loading: 'eager' on a slide to preload it:
Zoom
Set withZoom to enable zoom on image slides. Click an image to zoom in, use the scroll wheel to adjust
the zoom level and drag to pan. On mobile, double-tap to zoom and pinch to adjust.
Use zoomMaxScale to change the maximum zoom scale, 3 by default:
Click image to zoom, scroll to adjust, drag to pan when zoomed. Press Z to toggle zoom via keyboard.
Thumbnails
Set withThumbnails to display the thumbnail strip at the bottom. Users can hide it
with the T key or the toolbar button:
Custom thumbnails
Set renderThumb on a slide to render custom thumbnail content instead of an image, for
example a <video> element. The content is placed inside a square button, size it with
width: 100% and height: 100%:
All features
Zoom, thumbnails, fullscreen and download features can be combined. The download button saves files from your own origin. Files from other origins open in a new tab:
Loop navigation
Set loop to continue from the last slide to the first and back:
Slide transition
By default, slides change instantly. Set withSlideTransition to animate slide changes.
Use emblaOptions={{ duration: 40 }} to change the animation speed, embla duration is not in
milliseconds, values between 20 and 60 are recommended:
Embla options
Use emblaOptions prop to pass options to
the embla carousel. loop and startIndex options cannot be set this way, use loop and
currentIndex props instead:
z-index
zIndex controls the z-index of the overlay and the content elements, 400 by default:
Open and close transition
Use transitionProps to change the open and close animation, it accepts the same options
as the Transition component. To change only the duration, use
transitionDuration:
Disable animations
Set transitionProps={{ duration: 0 }} to open and close the lightbox without animation:
Swipe to close
On mobile, swiping down closes the lightbox. Set closeOnSwipeDown={false} to disable it:
Click outside to close
Set closeOnClickOutside to close the lightbox when an empty area is clicked.
This includes the space around the slide and the toolbar, caption and thumbnails backgrounds.
Clicks on images, videos, controls and caption text do not close it:
Store API
Mount Lightbox.Provider once in your app and open the lightbox from anywhere
with the static Lightbox methods:
Multiple lightboxes
To use several independent lightboxes, create a separate store with createLightbox
and pass it to the store prop of Lightbox.Provider:
Use the useLightboxStore hook to subscribe to the state of a lightbox store in a component:
Video slides
Set type: 'video' on a slide to render a <video> element. Videos are paused when the
slide changes. The poster image is used as the thumbnail:
Opens on a video slide with autoPlay. Navigate away to see the video pause automatically.
Custom slides
Set type: 'custom' and a render function to display any content in a slide.
Custom slides do not have a default thumbnail, set renderThumb or thumbSrc:
Custom toolbar
Use toolbarItems prop to replace the default toolbar items, including the close button.
Give each custom item a label that describes its action.
It accepts an array of items or a function. The function receives slides and the current index,
navigation and close handlers, thumbnails, fullscreen and zoom state with their toggles, and labels.
Use the built-in toolbar item factories for common actions:
Compound components
To change the layout of the lightbox, use compound components:
Lightbox.Thumbnails is rendered only when withThumbnails is set on Lightbox.Root.
Labels
Use labels prop to translate the lightbox:
To change labels for all lightboxes in your application, set labels in
default props of the Lightbox component.
Accessibility
Name the gallery with aria-label. Describe image slides with alt and video slides with label:
Keyboard shortcuts
Set withKeyboardEvents={false} to disable all shortcuts except Escape. Shortcuts are ignored
while focus is inside an input, a video or an interactive element of a custom slide: