Image Gallery
Responsive image figures with captions, ordinary destinations and separate native Dialog enlargement.
When to use it. Use it for a finite image collection. Choose lightbox=:none for ordinary browsing or when embedding inside another modal.
Image Gallery primary example
How it works
-
<.image_gallery>A named section with a list of figures, not a slideshow. Stable instance/item keys derive Dialog and caption identities. Each thumbnail button has a visible Enlarge name and a separate Open image link, never nested controls. No next/previous, selected image, swipe, zoom, pan, uploads, transformation, fetching service or listeners. -
package CSSPackage CSS applies scoped shadcn-style tokens, layout, focus, and state presentation without changing the native contract. -
gallery onlyTheme switching, source copying, search, fixtures, and inspection controls on this page belong to the gallery only; :image_gallery does not ship them. -
application boundaryShadcnUI does not add application state, authorization, persistence, transport events, or a JavaScript behavior layer to this component.
Examples use package semantic tokens in explicit light and dark scopes.
Accessibility and browser support
Keyboard Enter opens a named native Dialog with an explicit close control. The browser owns focus, inertness, Tab and Escape. Keyboard-invoked close returns to the previously focused thumbnail; pointer focus follows platform conventions. No focus trap is added. Full images always contain, and long captions scroll with the existing sticky close footer.
| Feature | Locked-engine evidence | When missing |
|---|---|---|
| Native baseline | Reviewed in the locked Chromium, Firefox, and WebKit evidence matrix. | Ordinary links remain visible without native commands, JavaScript or CSS. Destination priority is href, then full.src, then src. Failed images retain alt/name/caption/destination. The optional origin animation is deferred: Chromium reproduced it, Firefox/WebKit did not. All use existing native snap; missing anchors, transitions or reduced motion never prevent access. |
| Exact fallback | The locked-engine matrix retains the documented native or static outcome. | Ordinary links remain visible without native commands, JavaScript or CSS. Destination priority is href, then full.src, then src. Failed images retain alt/name/caption/destination. The optional origin animation is deferred: Chromium reproduced it, Firefox/WebKit did not. All use existing native snap; missing anchors, transitions or reduced motion never prevent access. |
Application ownership and API
You own image rights/privacy, CSP/origin policy, safe authorized URLs, meaningful alt/names, intrinsic dimensions, responsive candidates and destinations. Loading/decoding are browser hints, not guaranteed deferred fetching. Replacement resets native state; restoration is yours.
Attributes and item slots. Required id, exactly one accessible_label/labelledby, nonempty atom-keyed images (unique key, src, alt, positive width/height). Optional name, caption, href, width-candidate srcset with sizes, loading=:lazy|:eager, decoding=:async|:sync|:auto, and full map with its own src/dimensions/srcset/sizes. Decorative:true requires empty alt and independent name. columns=:two|:three|:four (three), density=:compact|:comfortable (comfortable), fit=:cover|:contain (cover), lightbox=:dialog|:none (dialog), motion=:system|:none. initial_focus=:auto|:content|:close, dismissal=:close_request|:none|:any, close_label defaults Close image. context=:dialog rejects dialog mode. Optional escaped description, class/rest. Repeated trusted noninteractive caption slots require key and receive %{key: key, context: :thumbnail|:full}; scope IDs and never embed controls or dialogs.
Provenance
Catalogue identity media.image-gallery, adapted from
unscripted/ui commit bd8f403030c8d1f46804da6eda733fde7e908e63
under its MIT notice.
The documentation presentation is adapted locally; ShadcnUI's Phoenix API and native semantic contract remain authoritative.
Adapt responsive thumbnail/native Dialog composition to keyed semantic HEEx figures with validated intrinsic/responsive metadata, alt intent, complete captions, explicit close and separate ordinary destinations. Reuse existing Dialog focus/dismissal; full images contain. Defer optional scoped origin transitions after actual three-engine evidence; no remote site artwork, next/previous state or command shim. Static prefixed utilities only, no new authored CSS block.