Skip to main content
Digitaltableteur

Design system components

Gallery

Masonry image grid with optional captions that appear on hover and keyboard focus, and a slight scale on hover and focus unless the user prefers reduced motion. Items open nothing. Used on work-detail and editorial pages where the imagery is the primary content.

Status: stable. Group: media. Markdown version: /design-system/components/gallery.md

When to use

Masonry image grid with captions revealed on hover and keyboard focus, used on case-study pages. Items open nothing. Provide meaningful alt text per image.

When not to use

  • Do not use as a navigation surface; gallery items are not links.
  • Do not put content in a caption that the page does not repeat elsewhere when touch users matter: captions show only on hover and focus.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

Gallery props
PropTypeDefaultDescriptionRequired
imagesGalleryImage[]noneNo description in the contract.Yes
minColumnWidthnumber320Accepted for API compatibility but not used: the column count follows fixed breakpoints (1 below 600px, 2 below 900px, 3 below 1200px, then 4).No
gutternumber32No description in the contract.No

Variants

No variant dimensions and no props with a fixed set of values.

Invalid combinations

The contract records no invalid combinations.

Keyboard

Gallery keyboard behaviour
KeyBehaviour
TabFocuses each gallery item and reveals its caption.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Gallery rules
LevelRuleHow it is checked
MUSTARIA: Each item is a figure; the image alt text and the figcaption describe it.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTARIA: Items are focusable only so keyboard users can reveal captions; they have no action.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTPositional, scale, and opacity motion is suppressed under prefers-reduced-motion.Manual review, last on 2026-11-04. WCAG 2.2.2, 2.3.3.
MUSTEvery documented keyboard interaction works as specified.Not yet verified: no evidence record. WCAG 2.1.1, 2.1.2.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-11-04.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { Gallery } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/content exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-gallery>; see the custom elements manifest.

Links