Playground

Image gallery

A thumbnail grid that opens a lightbox with previous and next.

  • Built on native elements
  • Each thumbnail is a button named by the image's required alt text, with aria-haspopup=dialog.
  • The lightbox is a modal dialog titled 'Image 2 of 5'; focus moves in, is trapped, and returns to the thumbnail on close.
  • ArrowLeft and ArrowRight (swapped in RTL) and the Previous and Next buttons move through the images and wrap; a horizontal swipe does the same; Escape closes.
  • Styles in one file: 02-buttons.css

Import

import '@monoline/css';
import {ImageGallery} from '@monoline/react';

Not installed yet? Pick a route.

Copies the source and its styles into your project.

npx monoline add image-gallery

Usage

import {ImageGallery, type GalleryImage} from '@monoline/react';

const tile = (n: number, fill: string) => `data:image/svg+xml;utf8,${encodeURIComponent(`<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 300"><rect width="400" height="300" fill="${fill}"/><text x="200" y="165" font-family="monospace" font-size="64" text-anchor="middle" fill="#fff">${n}</text></svg>`)}`;

const images: GalleryImage[] = ['#6b4f3a', '#3a5a6b', '#4f6b3a', '#6b3a5a', '#5a3a6b', '#3a6b5a'].map((c, i) => ({src: tile(i + 1, c), alt: `Sample picture ${i + 1}, a flat colour with its number`, caption: `Picture ${i + 1}`}));

<div style={{maxWidth: '480px'}}>
  <ImageGallery images={images} />
</div>

Examples

Grid and lightbox

Open a picture, then use the arrow keys, the buttons or a swipe. Escape closes.

Props

ImageGalleryProps

PropTypeDefaultDescription
images requiredGalleryImage[]–The images, in order. Each needs `alt` text.
columnsnumber3Number of columns in the thumbnail grid. Default 3.
onIndexChange((index: number) => void)–Called with the index of the image shown whenever the lightbox opens or moves.

Data Attributes

State is exposed through attributes. Style it with these selectors, not with class toggles.

This component sets no state attributes.

CSS classes

ClassStylesheet
.btn02-buttons.css
.btn-block02-buttons.css
.btn-danger02-buttons.css
.btn-ghost02-buttons.css
.btn-lg02-buttons.css
.btn-line02-buttons.css
.btn-sm02-buttons.css
.btn-solid02-buttons.css
.commanddialog.css
.dialog-closedialog.css
.dialog-contentdialog.css
.dialog-descriptiondialog.css
.dialog-footerdialog.css
.dialog-headerdialog.css
.dialog-overlaydialog.css
.dialog-titledialog.css
.drawer-contentdialog.css
.image-galleryimage-gallery.css
.image-gallery-figureimage-gallery.css
.image-gallery-lightboximage-gallery.css
.image-gallery-navimage-gallery.css
.image-gallery-thumbimage-gallery.css
.image-gallery-titleimage-gallery.css

Customization

Style it with the kit's tokens in your own CSS, loaded after @monoline/css. Prefer the attributes above over extra classes. See Theming for every token.

app.css
.btn {
  border-color: var(--accent);
}

Accessibility

  • Each thumbnail is a button named by the image's required alt text, with aria-haspopup=dialog.
  • The lightbox is a modal dialog titled 'Image 2 of 5'; focus moves in, is trapped, and returns to the thumbnail on close.
  • ArrowLeft and ArrowRight (swapped in RTL) and the Previous and Next buttons move through the images and wrap; a horizontal swipe does the same; Escape closes.
  • A polite status message announces the new image's alt text and position. Neighbouring images are preloaded.

Keyboard

KeysAction
ArrowLeft / ArrowRight(swapped in RTL) and the Previous and Next buttons move through the images and wrap
EscapeCloses