HyImageGalleryItem

Usage examples on this page are written for Lit / plain HTML (<hy-image-gallery-item>). The same component ships as HyImageGalleryItem 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 single cell within an hy-image-gallery. Provides an aspect-ratio crop box for a slotted image, an optional caption, per-item load/error states, and an optional interactive (button) or navigational (link) affordance.

Render modes (resolved in order)

• href set → <a href> (navigational; navigates natively, does not fire activate)
• interactive set → <button> (in-page action; fires activate on click / Enter / Space)
• otherwise → <figure> (presentational, not a focus stop)

All three carry role="listitem" on the host so the parent hy-image-gallery's role="list" announces "list, N items".

Image ownership stays with the author

This component takes no src. Slot the <img>/<picture> so you control srcset, sizes, loading, fetchpriority, and decoding. 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

Display-only cell

<hy-image-gallery-item caption="Sunset">
  <img src="/sunset.jpg" alt="Sunset over the lake" loading="lazy" decoding="async" />
</hy-image-gallery-item>

Interactive cell (opens a viewer)

<hy-image-gallery-item interactive>
  <img src="/photo.jpg" alt="Team photo" loading="lazy" decoding="async" />
</hy-image-gallery-item>

API

Properties

Property	Attribute	Type	Default	Description
href	href	string	''	If set, the cell renders as a navigational <a href>.
interactive	interactive	boolean	false	If set (and no href), the cell renders as a <button> and fires activate.
caption	caption	string	''	Convenience caption text; equivalent to slotting caption.
disabled	disabled	boolean	false	Disables an interactive/linked cell, preventing activation.
loading	loading	boolean	false	Force the per-item skeleton until the slotted image loads.

Events

Event	Detail	Description
activate	—	Fired when an interactive cell is activated. Detail: { originalEvent: MouseEvent | KeyboardEvent }

Slots

Slot	Description
default	The media (<img> / <picture>). Provide alt (descriptive, or alt="" for decorative).
caption	Caption content (richer than the caption string prop).

CSS Parts

Part	Description
cell	The cell wrapper (<figure> / <a> / <button>).
crop	The aspect-ratio crop box.
skeleton	The loading skeleton overlay.
broken	The broken-image fallback.
caption	The caption element.

CSS Custom Properties

Property	Description
--hy-image-gallery-item-surface	Crop-box / letterbox background.
--hy-image-gallery-item-border-color	Cell border color.
--hy-image-gallery-item-border-color-hover	Cell border color on hover (interactive).
--hy-image-gallery-item-border-width	Cell border width.
--hy-image-gallery-item-radius-top-start	Top-start corner radius.
--hy-image-gallery-item-radius-top-end	Top-end corner radius.
--hy-image-gallery-item-radius-bottom-start	Bottom-start corner radius.
--hy-image-gallery-item-radius-bottom-end	Bottom-end corner radius.
--hy-image-gallery-item-hover-duration	Hover transition duration.
--hy-image-gallery-item-hover-easing	Hover transition easing.

Methods

focus()

Focus the interactive cell (no-op for a static figure).