Skip to content
GaudiGaudi Design System home

Search documentation

Search every page, heading and paragraph.

ImageGallery

A responsive masonry or grid collection with an accessible image viewer.

CoreBasics@gaudi/design-system/core/ImageGalleryView in StorybookSource

A one-item collection is a full-width, click-to-expand image.

Installation

pnpm add github:ahmadassaf/design-system

Import from @gaudi/design-system. Load @gaudi/design-system/global.css once and add transpilePackages: ['@gaudi/design-system'] in Next.js.

import { ImageGallery } from '@gaudi/design-system/core/ImageGallery';

Usage

import { ImageGallery } from '@gaudi/design-system/core/ImageGallery';
<ImageGallery images={[{ id: 'lavender', src: '/static/images/art/0.svg', alt: 'Lavender gradient artwork', caption: 'A study in lavender and light', width: 1200, height: 675 }]} />

Examples

Playground

Storybook

Single expandable image

Storybook

Controlled grid

Storybook

Empty & unavailable images

Storybook

API

10 props

Accessibility

Thumbnails are named buttons. Enter or Space opens the viewer. Arrow keys move between images (respecting direction), Home and End select the first and last images, and Escape closes. Touch supports swiping and browser pinch zoom. Dialog contains focus and restores the opener, or the gallery region if that opener was removed or disabled. Reduced motion removes animated slide movement.

Notes

  • Provide useful alt text; captions add visible context. Offscreen slides are hidden from assistive technology. Navigation stops at either end and disappears for a single image.
  • Images load lazily, with the selected full image loaded eagerly. Failed sources show an accessible placeholder; replace thumbnailSrc (or src when no thumbnail is supplied) to recover a preview, and src to recover the full image. Empty collections show an explicit empty state.
  • Use one image in images for an expandable article figure. No separate single-image wrapper is needed. Existing MDX/Image and MDX/ImageModal share the same viewer while preserving their APIs.
  • The Shadix UI gallery informed the masonry and expansion behavior. The implementation uses Gaudi Dialog, Carousel, Button and Icon; it does not load remote demo resources.
NavigationThe site header block: brand, primary NavigationMenu with a two-block Blog panel (categories beside recent posts) or a Categories panel on the supplied blog route, search, theme switch, and a phone sheet below lg. LayoutContainer renders it from menuProps.ImageImage renders editorial MDX images with caption, dark-mode source, fallback source, and click-to-open modal behavior.ImageModalA focused view of an article image with a caption and dismiss action.DialogModal, confirmation and bare full-screen dialogs for editing, detail inspection, explicit decisions, lightboxes and launchers.12 examplesCarouselCarousel renders standard feature slides and editorial card rails.4 examplesButtonButton renders the Gaudi action and link-button variants.7 examples