` attribute passes through to the root.
| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `controls` | `boolean` | `true` | Show the prev/next arrow buttons. |
| `dots` | `boolean` | `false` | Show clickable pagination dots (one per slide). |
| `align` | `'start' \| 'center'` | `'start'` | Snap edge of each slide. |
| `itemWidth` | `string` | — | Fixed width applied to every slide (e.g. `"16rem"`). Omit to size each slide yourself. |
| `autoplay` | `boolean` | `false` | Auto-advance. Pauses on hover/focus; never runs under `prefers-reduced-motion`. |
| `interval` | `number` | `4000` | Autoplay delay in ms. |
| `loop` | `boolean` | `false` | With autoplay, jump back to the start after the last slide. |
| `label` | `string` | `'Carousel'` | Accessible name of the carousel region. |
| `controlsVariant` | `'default' \| 'overlay'` | `'default'` | `overlay`: borderless translucent arrows for image carousels. |
| `dotsPosition` | `'below' \| 'overlay'` | `'below'` | Dots under the track, or in a pill over its bottom edge. |
| `controlsPosition` | `'sides' \| 'below'` | `'sides'` | Arrows on the track’s sides, or in a row under it with the dots between them. |
| `visibleItems` | `Responsive<1 \| 2 \| 3 \| 4 \| 5 \| 6>` | — | Slides per view, per breakpoint (`{ base: 1, md: 3 }`); sizes every slide to fit, gap included. Overrides `itemWidth`. |
| `gap` | `2 \| 3 \| 4 \| 6 \| 8` | `4` | Space between slides, in spacing steps. |
| `bleed` | `boolean` | `false` | Let the track run under the page gutters. |
| `class` | `string` | — | Extra classes on the root, merged last. |
Slides go in the default slot, one top-level element per slide. Give each slide its own width, or set `itemWidth` for uniform slides.
## Variants
Snap alignment — `start` (default) vs `center`:
```astro
A
B
C
A
B
C
```
## Overlay controls
For image carousels: borderless translucent arrows and dots floating over the bottom edge. Arrows at an edge are disabled, not removed, so nothing shifts.
```astro
…
```
## Controls below
Put the arrows in a row under the slides when they would cover content, such as a quote. With `dots`, the dots sit between the arrows; without, the arrows sit at the end.
```astro
…
…
…
```
## Visible items, gap and bleed
```astro
…
…
… gap 3, 6, 8 …
…
```
## States
- **Hover / focus** — arrow buttons and dots lighten/highlight on hover; a visible `focus-visible` ring (`--border-primary`) on keyboard focus.
- **Active dot** — the dot for the in-view slide gets `aria-current="true"` and an accent fill; tracked live via `IntersectionObserver` as the user scrolls (not just on click).
- **No JS** — arrows and dots are hidden (`no-js:hidden`); the track itself has no disabled state, it’s always scrollable.
## Examples
With pagination dots:
```astro
1
2
3
```
Autoplay, looping, no arrow controls:
```astro
1
2
3
```
Self-sized slides (no `itemWidth` — each slide sets its own width):
```astro
Narrow
Wide
Narrow
```
On a brand fill (`bg-primary`), the current dot switches to the on-primary colour so it still stands out:
```astro
…
```
## Accessibility
| Key | Action |
| --- | --- |
| `Tab` | Moves focus to the track, then to Previous / Next and each dot. |
| `←` `→` | Scroll the focused track. |
| `Enter` `Space` | Activate the focused Previous / Next button or dot. |
- The track is a `region` with `aria-roledescription="carousel"`; each slide gets `aria-roledescription="slide"` and an `n of N` label.
- Arrows are 44px targets. At the first and last slide the arrow disables in place and focus moves to the other arrow; the track scrolls by touch and, once focused, by arrow keys.
- The root dispatches `apogee:carousel-change` (`detail: { index }`) when the visible slide changes.
- Prev/Next buttons carry `aria-label="Previous"` / `aria-label="Next"`.
- Dots sit in a `role="group"` (`aria-label="Slides"`); each dot button has `aria-label="Go to slide N"` and `aria-current` reflecting the in-view slide.
- **No JS** — arrows and dots are hidden entirely (`no-js:hidden`), not shown disabled; nothing is lost, since the track scrolls by touch, trackpad, or focused arrow keys regardless.
- **RTL** — under `dir="rtl"` the track runs right-to-left; Next scrolls toward the start edge and the arrow icons flip, so the controls read correctly.
- Autoplay pauses on hover and on focus, and never starts under `prefers-reduced-motion: reduce`.
## Tokens
| Token | Used for |
| --- | --- |
| `--border-neutral` | Arrow button border (default controls) |
| `--background-neutral` | Inactive dot fill |
| `--background-page` | Arrow button background |
| `--foreground-neutral` | Arrow icon color |
| `--background-page-faded` | Arrow button hover background |
| `--background-primary` | Active dot fill |
| `--outline-color-focus` | Focus ring on arrows and dots |
## Do / Don’t
- **Do** set `itemWidth` for uniform slides, or size each slide yourself for a mixed-width track.
- **Do** enable `dots` when there are few enough slides that a dot-per-slide stays scannable.
- **Don’t** put content a user _must_ see behind autoplay — they may miss a slide, and no-JS users never get it advancing at all.
- **Don’t** rely on the carousel as the only path to its content if any slide holds critical, unique information — link to it elsewhere too.
## Content
- Keep slide content self-contained — a user may land on any slide first (via a dot or a scroll), not always the first one.
- Alt text on slide images should describe the image, not “slide 1 of 4” — the dots already convey position.
## Related
[
ProgressIndicatorStep N of M as a row of segments, for onboarding flows, wizards and carousels. Zero JS.
](https://apogee.avaui.dev/docs/progress-indicator)[
ScrollAreaA scroll container with a thin, token-coloured scrollbar.
](https://apogee.avaui.dev/docs/scroll-area)[
MarqueeAn endless scrolling strip for logos, tags, or testimonials, with a play/pause toggle.
](https://apogee.avaui.dev/docs/marquee)