Image Gallery

Demo & usage

More examples

<sv-image-gallery
  [images]="images"
  layout="grid"
  [columns]="4"
  [captions]="true"
  [selectable]="true"
  [(selected)]="selectedImageIds" />

<sv-image-gallery
  [images]="page()"
  [selectable]="true"
  [(selected)]="chosen" />

// chosen lives in the HOST, so it survives the page change:
readonly chosen = signal<Set<string>>(new Set());

When to use

• Displaying a collection of images users browse and open full-screen.
• You want grid/masonry/strip layouts plus a keyboard-friendly lightbox.
• For a single rotating banner, use the Carousel.

Async states

• loading
• empty
• error
• retry

Item identity & owned state

Restorable state

• selected

Bind these to put a saved view back — the open sections, the hidden columns, the selected rows — and read their Change events to store what the user does.

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

<sv-image-gallery
  [images]="data.items()"
  [loading]="data.loading()"
  [error]="data.error()"
  [filtered]="data.filtered()"
  (retry)="data.reload()"
/>

// This component reports its state but does not emit a query, so drive
// it from your own fetch and bind the three async inputs.
readonly items = signal<Row[]>([]);
readonly loading = signal(false);
readonly error = signal<SvDataError | null>(null);

async load(): Promise<void> {
  this.loading.set(true);
  this.error.set(null);
  try {
    this.items.set(await this.api.fetchRows());
  } catch (e) {
    this.error.set(toSvDataError(e));
  } finally {
    this.loading.set(false);
  }
}

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `images`, `loading` and `error`.
• Set `filtered` when a search or filter is active. It is the difference between "you have no orders" and "no orders match this filter" — telling a customer with 4,000 orders the first one reads as a bug.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Grid, masonry or strip layouts (2–5 columns).
• Lightbox with keyboard navigation.
• Optional selectable mode.
• Product-viewer layout: a large main image with hover-zoom (zoomLevel) and a thumbnail strip to switch images.

Best practices

• Do: Provide descriptive `alt` text on every image for accessibility and SEO.
• Do: Serve appropriately sized thumbnails; load full-res only in the lightbox.
• Tip: Enable `selectable` for bulk operations like delete or add-to-album.
• Do: Hold `selected` in the host — a signal, a store, a route param. It is the only place a selection can survive a page turn, and the component will not prune it behind your back.
• Don't: Don't clear the selection yourself on every `images` change. That is the tidying the component avoids on purpose, and it deletes exactly the choices the user made on the previous page.

Accessibility

• Focus after a mutation (X-12): closing the lightbox returns focus to the control that opened it — or, if the reader paged to another image, to THAT image's thumbnail (the viewer layout also makes it the active image). If neither survives, focus goes into the gallery, never `<body>`.
• Every layout is a `<ul role="list">`, so a listener is told the images are ONE SET OF A KNOWN SIZE — "list, 12 items" — which was the only fact the grid conveyed visually and nothing carried. A table of alt texts would be the alt texts again in a worse container, so there is no companion summary here.
• The `role="list"` is not redundant: Tailwind's preflight strips `list-style`, and that alone is enough for Safari/VoiceOver to stop treating the `<ul>` as a list.
• Name the gallery with `ariaLabel` when a page has more than one.
• The lightbox is a modal `dialog` with a focus trap; focus returns to the originating thumbnail on close, and ←/→/Esc navigate.
• Built with safe DOM APIs (no HTML injection), so image-supplied alt/title/author cannot inject markup.
• View and select controls are labelled buttons reachable by keyboard in every layout; images require descriptive alt text.
• A selection that outlives the page it was made on is disclosed in a `role="status"` strip — "12 selected — 9 not on this page" — because the component deliberately never prunes ids for images it cannot see, and a reader who cannot tell would believe the selection is only what is ticked in front of them.