# Carousel

> A row of slides to swipe or step through.

- **Level**: molecule · **Status**: stable · **Role**: content
- **Import**: `import { Carousel, CarouselAutoplayToggle, CarouselControls, CarouselCounter, CarouselNextButton, CarouselPagination } from "@rrios-forge/ui/molecules/carousel";`
- **Source**: `packages/ui/src/molecules/carousel`

Apple-grade carousel built on `embla-carousel-react`. Compound API:
`Carousel` + `CarouselViewport` + `CarouselSlide` + optional
`CarouselControls`, `CarouselPreviousButton`, `CarouselNextButton`,
`CarouselPagination`, `CarouselCounter`.

Supports horizontal and vertical layouts, single or multi-item per
view, loop, autoplay (with WCAG 2.2.2 pause-on-hover / pause-on-focus
and reduced-motion opt-out), touch/drag, and full keyboard navigation
(arrows + Home / End) on the Root region.

Integrates with every Card-family surface in the system: `Card`,
`MetricCard`, `PlanCard`, `PricingOption`, `FeedCard`. Each slide is
an inert container; the focused content lives inside it.

Patterns consulted: `Patterns/Information Architecture · Progressive
disclosure`, `Patterns/Composition · Compound components`,
`Patterns/Visual Priority · Action hierarchy`, `Patterns/Density &
Growth · Touch-target floor`, `Patterns/Page Shells · Dashboard surface`.

## Axes

| Axis | Part | Values | Default | Meaning |
|---|---|---|---|---|
| `orientation` | — | `horizontal` `vertical` | `horizontal` | The direction the parts run: a row (horizontal) or a column (vertical); responsive stacks on phones and runs in a row from sm. |
| `placement` | — | `inset` `below` `floating-bottom` | `below` | Where an attached element sits. |
| `side` | — | `previous` `next` | `previous` | Which side something belongs to. |
| `presentation` | — | `plain` `capsule` | `capsule` | How the same thing is staged. |

## Stories

- [Playground](/?path=/story/components-molecules-carousel--playground) · frame: `/iframe.html?id=components-molecules-carousel--playground&viewMode=story`
- [Multi-item per view](/?path=/story/components-molecules-carousel--multi-item-view) · frame: `/iframe.html?id=components-molecules-carousel--multi-item-view&viewMode=story`
- [Control placements](/?path=/story/components-molecules-carousel--control-placements) · frame: `/iframe.html?id=components-molecules-carousel--control-placements&viewMode=story`
- [Loop + autoplay](/?path=/story/components-molecules-carousel--loop-and-autoplay) · frame: `/iframe.html?id=components-molecules-carousel--loop-and-autoplay&viewMode=story`
- [Vertical](/?path=/story/components-molecules-carousel--vertical) · frame: `/iframe.html?id=components-molecules-carousel--vertical&viewMode=story`
- [Integration — Carousel of Cards](/?path=/story/components-molecules-carousel--with-card) · frame: `/iframe.html?id=components-molecules-carousel--with-card&viewMode=story`
- [Integration — MetricCard](/?path=/story/components-molecules-carousel--with-metric-cards) · frame: `/iframe.html?id=components-molecules-carousel--with-metric-cards&viewMode=story`
- [Integration — PricingOption](/?path=/story/components-molecules-carousel--with-pricing-options) · frame: `/iframe.html?id=components-molecules-carousel--with-pricing-options&viewMode=story`
- [With counter](/?path=/story/components-molecules-carousel--with-counter) · frame: `/iframe.html?id=components-molecules-carousel--with-counter&viewMode=story`
- [Inset controls](/?path=/story/components-molecules-carousel--inset-controls) · frame: `/iframe.html?id=components-molecules-carousel--inset-controls&viewMode=story`
- [In context](/?path=/story/components-molecules-carousel--in-context) · frame: `/iframe.html?id=components-molecules-carousel--in-context&viewMode=story`
- [Accessibility notes](/?path=/story/components-molecules-carousel--accessibility-notes) · frame: `/iframe.html?id=components-molecules-carousel--accessibility-notes&viewMode=story`
- [Integration — Card with embedded Carousel](/?path=/story/components-molecules-carousel--card-with-carousel) · frame: `/iframe.html?id=components-molecules-carousel--card-with-carousel&viewMode=story`
- [Integration — Card with vertical Carousel](/?path=/story/components-molecules-carousel--card-with-vertical-carousel) · frame: `/iframe.html?id=components-molecules-carousel--card-with-vertical-carousel&viewMode=story`
- [Integration — Card with metric snapshot Carousel](/?path=/story/components-molecules-carousel--card-with-metrics-carousel) · frame: `/iframe.html?id=components-molecules-carousel--card-with-metrics-carousel&viewMode=story`
- [Keyboard flow (interaction test)](/?path=/story/components-molecules-carousel--keyboard-flow) — interaction test · frame: `/iframe.html?id=components-molecules-carousel--keyboard-flow&viewMode=story`

## Always

- Tokens only (R04); variants are semantic axes, never appearance (R02).
- Typography and actions are Poesía atoms, never raw HTML with utilities.
- Vibrant panes need a ground and never nest (ADR-027).