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.

Used inside <hy-image-gallery> — it only means something as part of it.

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.

When not to use

• An image with a title, metadata and buttons: hy-card.

Accessibility: your part

• Write a caption that adds to the image. Do not repeat its alt text.

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	''	The caption under the image.
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).

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

The documented hooks. Every override hook the component reads — one per token it paints — is listed in @whitespaceux/harmony/theme-api.json, and @whitespaceux/harmony/component-bindings.json (the Harmony MCP get-bindings tool) says which part and state each one paints.

Property	Default	Description
--hy-image-gallery-item-surface-background-surface-base	var(--hy-background-surface-base)	Cell background.
--hy-image-gallery-item-crop-background-surface-medium	var(--hy-background-surface-medium)	Background behind the image: around a fitted (object-fit="contain") image, behind a transparent one, under the broken-image fallback. Default: the medium surface, as the loading skeleton.
--hy-image-gallery-item-border-subtle-rest	var(--hy-border-subtle-rest)	Cell border color.
--hy-image-gallery-item-border-default-rest	var(--hy-border-default-rest)	Cell border color on hover (interactive).
--hy-image-gallery-item-stroke-sm	var(--hy-stroke-sm)	Cell border width.
--hy-image-gallery-item-radius-container-md-top-start	var(--hy-radius-container-md-top-start)	Top-start corner radius.
--hy-image-gallery-item-radius-container-md-top-end	var(--hy-radius-container-md-top-end)	Top-end corner radius.
--hy-image-gallery-item-radius-container-md-bottom-start	var(--hy-radius-container-md-bottom-start)	Bottom-start corner radius.
--hy-image-gallery-item-radius-container-md-bottom-end	var(--hy-radius-container-md-bottom-end)	Bottom-end corner radius.
--hy-image-gallery-item-motion-transition-hover-duration	var(--hy-motion-transition-hover-duration)	Hover transition duration.
--hy-image-gallery-item-motion-transition-hover-easing	var(--hy-motion-transition-hover-easing)	Hover transition easing.
--hy-image-gallery-item-aspect-ratio	—	Crop aspect ratio; set by hy-image-gallery from its --hy-image-gallery-aspect-ratio (1 / 1 standalone)
--hy-image-gallery-item-object-fit	—	How the image fills the crop box; set by hy-image-gallery from its --hy-image-gallery-object-fit (cover standalone)

Methods

focus()

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