HyImageGallery

Usage examples on this page are written for Lit / plain HTML (<hy-image-gallery>). The same component ships as HyImageGallery in @whitespaceux/harmony-react (native React 19), with typed wrappers for Angular, Solid, Svelte, and Vue. The API reference below applies to all frameworks.

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>

API

Properties

Property	Attribute	Type	Default	Description
columns	columns	ImageGalleryColumns	'auto'	'auto' (responsive auto-fit) or a fixed number of columns.
minColumn	min-column	string	'16rem'	Minimum column width for the auto grid. Maps to --hy-image-gallery-min-column.
gap	gap	string	''	Gap override; default comes from --hy-image-gallery-gap.
aspectRatio	aspect-ratio	string	'1 / 1'	Uniform crop aspect ratio for every item. 'auto' requires layout="masonry".
objectFit	object-fit	'cover' | 'contain'	'cover'	How items fill their crop box.
layout	layout	'uniform' | 'masonry'	'uniform'	Layout mode. masonry is progressive-enhancement.
label	label	string	''	Accessible name for the list region (aria-label).
state	state	'idle' | 'loading' | 'empty' | 'error'	'idle'	Data-region state (consumer-driven).

Events

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

Slots

Slot	Description
default	The hy-image-gallery-item children.

CSS Parts

Part	Description
base	The grid list (<ul role="list">).

CSS Custom Properties

Property	Description
--hy-image-gallery-gap	Gap between cells.
--hy-image-gallery-min-column	Minimum column width for the auto grid.
--hy-image-gallery-aspect-ratio	Uniform crop aspect ratio (cascades to items).
--hy-image-gallery-object-fit	How items fill their crop box (cascades to items).