wb-gallery is good at equal-tile responsive image collections and one shared modal viewer. It is not a layout system, not masonry, not a featured-grid pattern, and not a carousel.Use this page when the job is to present a set of images cleanly in the page flow, optionally with captions and one shared viewer modal. If you need mixed media, zoom, hero-plus-thumbnails, or uneven tile sizing, the current shipped contract is the wrong fit.
When to use
- Image collections
- Screenshot sets
- Editorial visuals
- Inline content galleries
Core contract
Keep the base markup small. The gallery pattern is an inline grid wrapper, an item wrapper, one interactive trigger, one image, and optional caption or meta text.
<div class="wb-gallery" aria-label="Release gallery">
<div class="wb-gallery-grid">
<figure class="wb-gallery-item">
<button class="wb-gallery-trigger"
type="button"
data-wb-gallery-target="#releaseViewer"
data-wb-gallery-full="/images/release-full.jpg">
<img class="wb-gallery-media"
src="/images/release-thumb.jpg"
alt="Release dashboard screenshot">
</button>
<figcaption class="wb-gallery-caption">Release dashboard</figcaption>
<div class="wb-gallery-meta">Shared viewer modal</div>
</figure>
</div>
</div>| Hook | Real support | Notes |
|---|---|---|
data-wb-gallery-target | Yes | Preferred gallery-to-modal connection hook. |
data-wb-target | Yes | Accepted as a fallback modal selector source. |
data-wb-gallery-full | Yes | Full-size viewer image source. |
data-wb-gallery-alt | Yes | Viewer alt text override. |
data-wb-gallery-caption | Yes | Viewer caption override. |
data-wb-gallery-meta | Yes | Viewer meta override. |
data-wb-gallery-width | Yes | Optional width attribute for viewer image. |
data-wb-gallery-height | Yes | Optional height attribute for viewer image. |
<div class="wb-modal wb-modal-xl" id="releaseViewer" role="dialog" aria-modal="true" aria-labelledby="releaseViewerTitle">
<div class="wb-modal-dialog">
<div class="wb-modal-body">
<div class="wb-gallery-viewer">
<div class="wb-gallery-viewer-toolbar">
<button class="wb-gallery-viewer-prev" type="button" aria-label="Previous image">...</button>
<div class="wb-gallery-viewer-counter" aria-live="polite">1 / 3</div>
<button class="wb-gallery-viewer-next" type="button" aria-label="Next image">...</button>
<button class="wb-gallery-viewer-close" type="button" data-wb-dismiss="modal" aria-label="Close viewer">...</button>
</div>
<figure class="wb-gallery-viewer-media">
<img class="wb-gallery-viewer-image" src="..." alt="...">
<figcaption class="wb-gallery-viewer-caption" id="releaseViewerTitle"></figcaption>
</figure>
<p class="wb-gallery-viewer-meta"></p>
</div>
</div>
</div>
</div>Official examples
These six examples are the strongest current uses of wb-gallery. Each one demonstrates a different job without pretending the pattern can do masonry, featured spans, or slider behavior.
1. Inline captioned gallery
Baseline pattern: equal tiles with one visible caption per image. This example uses the same shared viewer pattern for a consistent docs experience.
2. Gallery with metadata
Second text layer: the gallery keeps the same equal-tile structure but adds muted support text below each caption. It uses the same shared viewer without turning metadata into a new gallery type.
4. Editorial/content gallery block
Content integration: the gallery sits inside a readable article flow instead of pretending to be a standalone layout engine. The same shared viewer stays available without breaking the editorial context.
Case-study image block
Use wb-gallery inside a content shell when an article or case study needs a calm inline media group.
These images support the story; they do not replace the page hierarchy. The gallery stays equal-tile, readable, and easy to drop into long-form content.
5. Card-contained media gallery
App/dashboard usage: the gallery lives inside a framed surface with header and body rhythm. It still uses the same shared viewer pattern instead of ejecting users into raw image tabs.
Recent launch assets
Viewer boundaryUse this composition for release recaps, property/image modules, or detail surfaces that need a compact image set inside one card.
6. Product screenshot gallery
Realistic product usage: screenshot sets work well when each frame has similar importance and the page does not need a featured hero-plus-thumbnail relationship. This example also opens through the same shared viewer pattern for consistency.
Atlas product tour
A clean equal-tile screenshot set is often enough for feature overviews, release notes, and docs pages.
Composition guidance
wb-gallery combines cleanly with wb-card, wb-content-shell, wb-stack, wb-split, and wb-grid-* helpers. These are composition patterns, not gallery variants.
Do / Do not
Do
Use equal-importance image sets.
Keep one shared viewer modal for the gallery context instead of duplicating viewers per example.
Use real captions and optional meta only when they add context.
Combine with content shells, cards, and layout helpers when the page job needs it.
Do not
Do not imply masonry.
Do not imply featured spans or hero-plus-thumbnails.
Do not imply carousel, zoom, or mixed-media support.
Do not add docs-only helper classes just to fake unsupported gallery behavior.
Accessibility / behavior notes
data-wb-gallery-alt first, then falls back to the inline image alt.data-wb-gallery-caption and data-wb-gallery-meta first, then falls back to wb-gallery-caption and wb-gallery-meta text.id, the modal uses aria-labelledby. Otherwise it falls back to an aria-label from caption, alt, or the text "Gallery viewer"..wb-gallery that point to the same modal selector.