React-spring-lightbox is a flexible image gallery lightbox with native-feeling touch gestures and buttery smooth animations.
- ☝️
Mousewheel, swipe or click+drag to page photos - ⌨️ Keyboard controls ← → Esc that leave the rest of the page alone
- ♿ Opens as a modal dialog that takes focus and gives it back when it closes
- 🐁 Ctrl +
MousewheelorTrackpad Pinchto zoom - 🔎 Double/Single-tap or double/single-click to zoom in/out
- 👌 Pinch to zoom
- 👈 Panning on zoomed-in images
- 🏁 Highly performant spring based animations via react-spring
- No external CSS
- Implement your own UI
- Supports IE 11, Edge, Safari, Chrome, Firefox and Opera
- Full typescript support
- Supports any
<img />attribute includingloading(lazy loading),srcsetandaria-*
yarn add react-spring-lightboxThe images prop now accepts a list of objects whose properties can be almost any valid React <img /> prop including srcset, loading (lazy loading) and aria-* attributes.
If you use typescript, the exact type can be imported from import { ImagesListType } from 'react-spring-lightbox';
import React, { useState } from 'react';
import Lightbox, { ImagesListType } from 'react-spring-lightbox';
const images: ImagesListType = [
{
src: 'https://timellenberger.com/static/blog-content/dark-mode/win10-dark-mode.jpg',
loading: 'lazy',
alt: 'Windows 10 Dark Mode Setting',
},
{
src: 'https://timellenberger.com/static/blog-content/dark-mode/macos-dark-mode.png',
loading: 'lazy',
alt: 'macOS Mojave Dark Mode Setting',
},
{
src: 'https://timellenberger.com/static/blog-content/dark-mode/android-9-dark-mode.jpg',
loading: 'lazy',
alt: 'Android 9.0 Dark Mode Setting',
},
];
const CoolLightbox = () => {
const [currentImageIndex, setCurrentIndex] = useState(0);
const gotoPrevious = () =>
currentImageIndex > 0 && setCurrentIndex(currentImageIndex - 1);
const gotoNext = () =>
currentImageIndex + 1 < images.length &&
setCurrentIndex(currentImageIndex + 1);
return (
<Lightbox
isOpen={true}
onPrev={gotoPrevious}
onNext={gotoNext}
images={images}
currentIndex={currentImageIndex}
/* Name the dialog for screen readers */
aria-label="Dark mode settings"
/* Add your own UI */
// renderHeader={() => (<CustomHeader />)}
// renderFooter={() => (<CustomFooter />)}
// renderPrevButton={() => (<CustomLeftArrowButton />)}
// renderNextButton={() => (<CustomRightArrowButton />)}
// renderImageOverlay={() => (<ImageOverlayComponent >)}
/* Add styling */
// className="cool-class"
// style={{ background: "grey" }}
/* Handle closing */
// onClose={handleClose}
/* Use single or double click to zoom */
// singleClickToZoom
/* react-spring config for open/close animation */
// pageTransitionConfig={{
// from: { transform: "scale(0.75)", opacity: 0 },
// enter: { transform: "scale(1)", opacity: 1 },
// leave: { transform: "scale(0.75)", opacity: 0 },
// config: { mass: 1, tension: 320, friction: 32 }
// }}
/>
);
};
export default CoolLightbox;| Prop | Description |
|---|---|
| isOpen | Flag that dictates if the lightbox is open or closed |
| onClose | Function that closes the Lightbox |
| onPrev | Function that changes currentIndex to previous image in images |
| onNext | Function that changes currentIndex to next image in images |
| currentIndex | Index of image in images array that is currently shown |
| renderHeader | A React component that renders above the image pager |
| renderFooter | A React component that renders below the image pager |
| renderPrevButton | A React component that is used for previous button in image pager |
| renderNextButton | A React component that is used for next button in image pager |
| renderImageOverlay | A React component that renders within the image stage, useful for creating UI overlays on top of the current image |
| singleClickToZoom | Overrides the default behavior of double clicking causing an image zoom to a single click |
| images | Array of image objects to be shown in Lightbox |
| className | Classes are applied to the root lightbox component |
| style | Inline styles are applied to the root lightbox component |
| pageTransitionConfig | React-Spring useTransition config for page open/close animation |
| aria-label | Names the lightbox dialog for screen readers. Use this or aria-labelledby |
| aria-labelledby | The id of an element, such as a title in renderHeader, that names the lightbox dialog |
The lightbox opens as a modal dialog with role="dialog" and aria-modal="true". When it opens, focus moves into it, and Tab and Shift+Tab cycle through its controls. Until it closes, the other children of <body> are inert, so neither the keyboard nor a screen reader reaches the page behind it, and <html> has overflow: hidden, so the page behind it doesn't scroll. When it closes, focus goes back to the element that had focus before it opened. With inline, the lightbox is part of the page and none of this applies.
- Name the dialog with
aria-label, or witharia-labelledbyand theidof a title in your header. - Give each button that you render a text label or an
aria-label. An icon alone gives a screen reader nothing to announce. - Elements that you add to
<body>after the lightbox opens, such as a menu that a header button portals to<body>, stay usable. Elements that were in<body>before it opened stay inert until it closes.
The lightbox handles ←, →, and Esc only while focus is inside it, or while the modal lightbox is open and nothing has focus, as after a focused Next button turns disabled on the last image. Text fields and selects inside it keep their arrow, Home, and End keys.
- To keep the lightbox open when a control inside it handles Esc, call
event.preventDefault()in that control'sonKeyDown. - An
inlinecarousel takes ← and → only while focus is inside it. Render buttons withrenderPrevButtonandrenderNextButton, so keyboard users can move focus there. A button that turnsdisabledwhile it has focus, as at the first or last image, drops focus to the page, and the carousel then takes no keys until focus is back inside it.
Clone the repo
git clone https://github.com/tim-soft/react-spring-lightbox.git react-spring-lightbox
cd react-spring-lightboxInstall the library's dependencies
npm installRun the library in development mode, which rebuilds it on every change
npm startIn another terminal, install and run the example app. Its file: dependencies are symlinks to the library and to the library's own React, so both use one copy of React.
cd example
npm install
npm run devChanges to the library code should hot reload in the demo app
Every pull request needs a changeset, a short note in .changeset/ that says what changed for people who use the library and whether that's a patch, minor or major change. The changeset check fails without one.
npm run chFor a change that doesn't need a release, such as one to tests or CI, add an empty changeset instead.
npx changeset add --emptyOnce changesets reach master, a Version Packages pull request collects them. It bumps the version and adds a dated entry to CHANGELOG.md. Merging it publishes the new version to npm, tags it, and creates its GitHub release.
MIT © Tim Ellenberger