HyImageGallery

A responsive, accessible, CLS-free grid of slotted images. Lays out hy-image-gallery-item children, enforces a uniform aspect ratio, and emits a click contract (item-click) that a separate viewer (e.g. a dialog) can consume.

Grid-only by design — the full-screen lightbox is a separate concern (compose item-click with hy-dialog). Uses list semantics (role="list" here, role="listitem" on each item) and native Tab order, not a custom keyboard grid.

Performance

The author owns each <img>. Eager-load (and fetchpriority="high") the first row for LCP; lazy-load the rest. The fixed aspect-ratio crop box reserves space so there is no layout shift while images load.

Examples

Responsive grid

<hy-image-gallery label="Photos">
  <hy-image-gallery-item caption="One"><img src="/1.jpg" alt="One" /></hy-image-gallery-item>
  <hy-image-gallery-item caption="Two"><img src="/2.jpg" alt="Two" /></hy-image-gallery-item>
</hy-image-gallery>

Open a viewer on click

<hy-image-gallery label="Photos">
<hy-image-gallery-item interactive><img src="/1.jpg" alt="One" /></hy-image-gallery-item>
</hy-image-gallery>
<script>
gallery.addEventListener('item-click', (e) => openDialog(e.detail.index));
</script>

Events

• item-click - An interactive item was activated. Detail: { index: number, item: HyImageGalleryItem }
• retry - The error-state retry button was clicked. Detail: {}

Slots

• default - The hy-image-gallery-item children.