All components (204)

Gallery

Commerce · Gallery · .amset-gallery

What it is and when to use it

The photo viewer of a product page: the large photo and, below, the strip of thumbnails to choose another.

When to use it

The photos of a product, of which one is viewed at a time.
thumbnails={false} when there is no room for the strip: the arrows and the counter remain (arrows and counter remove them too).
ratio fixes the shape of the slot (1:1, 4:3 or 16:9) so the page does not jump on load; free respects the photo.
Controlled with index and onChange, for example to change the photo when a color is chosen; uncontrolled, initialIndex is the starting one.

When not to

A strip of things seen several at once (cards, new arrivals): Carousel.
A single photo: Thumbnail.
Two photos of the same framing to compare: ImageCompare.

Keyboard: the strip is a list of tabs: Tab enters through the chosen thumbnail and the arrow keys change the photo. The next Tab goes to the large photo and then to the previous and next photo buttons, which are disabled at the ends.

Accessibility: each thumbnail is a tab named after the alt of its photo (the small image is decorative) and the large photo is its panel: the relationship between the two is in the HTML, not just drawn. The alt of each photo is required. The counter ("2 of 4") is a role="status", so the change is announced. Without thumbnails, it is a group named after the label.

Fine-tuning: CSS variables --amset-gallery-*: -arrow, -arrow-icon, -counter, -gap, -radius, -thumbnail. The size moves the arrow, its icon, the thumbnail and the counter.

What it looks like

1 of 2

<Gallery
  label="Product photos"
  images={[
    { key: '1', src: '/frente.jpg', alt: 'Front view' },
    { key: '2', src: '/lado.jpg', alt: 'Side view' },
  ]}
/>

Props

Import it with import { Gallery } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`images`required	`readonly GalleryImage[]`	—
`label`required	`string`	What the photos are of: "Photos of the Aurelia ring".
`arrows`	`boolean`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`counter`	`boolean`	—
`index`	`number`	—
`initialIndex`	`number`	—
`onChange`	`(index: number) => void`	—
`ratio`	`GalleryRatio`	Shape of the slot of the large photo. `free` respects the image.
`size`	`"sm" \| "md" \| "lg"`	—
`thumbnails`	`boolean`	Strip of thumbnails below. Without it, only the arrows and the counter remain.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-gallery-gap`	`var(--amset-space-2)`
`--amset-gallery-radius`	`var(--amset-radius-lg)`
`--amset-gallery-arrow`	`2.25rem`
`--amset-gallery-arrow-icon`	`1.125rem`
`--amset-gallery-counter`	`var(--amset-text-xs)`
`--amset-gallery-thumbnail`	`4rem`

How to change it

.amset-gallery {
  --amset-gallery-gap: ...;
  --amset-gallery-radius: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: