All components (204)

Carousel

Commerce · Carousel · .amset-carousel

What it is and when to use it

A strip of things to move through: the photos of a product or a row of cards that does not fit. At the top go the counter and the previous and next buttons; below, the dots.

When to use it

"New arrivals", "You may also like": cards that are moved through perView by perView.
Photos that are moved through one by one, all equally important.
loop so that after the last one it returns to the first; by default the end is noticeable.
automatic (in seconds) only if it is really needed: the pause button appears, it stops when the mouse hovers over it or when focus enters, and it does not start if the system asks for reduced motion.
index and onChange to drive the slide from outside; points={false} removes the dots.

When not to

The photos of a product, of which one is viewed at a time and with thumbnails: Gallery.
Sections of which only one matters: Tabs.
A whole product listing: a grid of ProductCard, which hides nothing.

Keyboard: Tab goes through the pause button (if it moves by itself), previous and next, the track (which is focused because it scrolls, and is moved through with the arrow keys like any scrollable area), whatever is inside the slides and the dots. Previous and next are disabled at the ends, except with loop.

Accessibility: it is a region announced as "carousel", with its label (required), and each slide as "slide" with its position and its name (the slide's label: "2 of 4: Small hoop earrings"). The change is announced only when requested by hand: when it moves by itself it does not speak. Focus is never moved on change. The counter and the dots tell the slide that is visible, also if it was reached by scrolling with a finger or the wheel (and onChange finds out). The current dot changes shape, not just color, and it is pressed at 44 px even though it looks small.

Fine-tuning: CSS variables --amset-carousel-*: -counter, -dot, -dot-current, -dot-target, -gap. The size moves the dot and the gap between dots. The gap is NOT free-standing: it comes from -dot-target, which is what is pressed, so that the area of one dot does not eat into its neighbor's.

What it looks like

One new item.

Another update.

And one more.

<Carousel
  label="What's new"
  slides={[
    { key: 'a', label: 'First', content: <Novedad /> },
    { key: 'b', label: 'Second', content: <Novedad /> },
  ]}
/>

Props

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

Prop	Type	What it does
`label`required	`string`	Required: it is what is announced on entering the carousel.
`slides`required	`readonly CarouselSlide[]`	—
`automatic`	`number`	Seconds between automatic jumps. Without it it does not move by itself, which is the healthy default. When set, the pause button appears, it stops on hover or when focus enters, and it does not start if the system asks for less motion.
`className`	`string`	Merged with the library classes; it does not replace them.
`index`	`number`	Controlled: takes the track to that slide on mounting and every time it changes. The counter and the dots always say the one that is showing, also if it was reached by scrolling with a finger or the wheel.
`loop`	`boolean`	On reaching the end it goes back to the start. Not by default: the end is noticeable.
`onChange`	`(index: number) => void`	Notifies of the new slide when changing with the buttons, the dots, the automatic movement or by scrolling the track. It does not notify of what arrives through `index`, which whoever sets it already knows.
`perView`	`number`	How many are visible at once. One by default.
`points`	`boolean`	The position dots below. Shown by default.
`size`	`"sm" \| "md" \| "lg"`	—

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-carousel-gap`	`var(--amset-space-2)`
`--amset-carousel-dot`	`0.5rem`
`--amset-carousel-dot-current`	`1.25rem`
`--amset-carousel-dot-target`	`1.5rem`
`--amset-carousel-counter`	`var(--amset-text-xs)`

How to change it

.amset-carousel {
  --amset-carousel-gap: ...;
  --amset-carousel-dot: ...;
}

In the test bench

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