# Carousel Primitive

Carousel is a Starwind Runtime primitive in the viewport-measurement contract family.
## Anatomy
### Astro
Use the Astro primitive adapter to render Carousel anatomy with the Runtime wiring included.
```astro
---
import { Carousel } from "@starwind-ui/astro/carousel";
---

<Carousel.Root>
  <Carousel.Viewport>
    <Carousel.Container>
      <Carousel.Item>Slide 1</Carousel.Item>
    </Carousel.Container>
  </Carousel.Viewport>
  <Carousel.Previous>Previous</Carousel.Previous>
  <Carousel.Next>Next</Carousel.Next>
</Carousel.Root>
```

### React
Use the React primitive adapter when Carousel state participates in React rendering.
```tsx
import { Carousel } from "@starwind-ui/react/carousel";

export function Example() {
  return (
    <Carousel.Root>
      <Carousel.Viewport>
        <Carousel.Container>
          <Carousel.Item>Slide 1</Carousel.Item>
        </Carousel.Container>
      </Carousel.Viewport>
      <Carousel.Previous>Previous</Carousel.Previous>
      <Carousel.Next>Next</Carousel.Next>
    </Carousel.Root>
  );
}
```

### HTML
Render the Carousel data-sw-* contract yourself, then initialize createCarousel.
```html
<div data-sw-carousel role="region" aria-roledescription="carousel">
  <div data-sw-carousel-viewport>
    <div data-sw-carousel-container>
      <div data-sw-carousel-item role="group" aria-roledescription="slide">Slide 1</div>
    </div>
  </div>
  <button data-sw-carousel-previous type="button">Previous</button>
  <button data-sw-carousel-next type="button">Next</button>
</div>

<script type="module">
  import { createCarousel } from "@starwind-ui/runtime/carousel";

  const root = document.querySelector("[data-sw-carousel]");
  if (root) {
    createCarousel(root);
  }
</script>
```
## API Reference
### Root
The main element that owns the Carousel Runtime instance.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel` |
| Role | `region` |
#### Props
| Prop | Type | Default | Kind | Description |
| --- | --- | --- | --- | --- |
| orientation | `"horizontal" \| "vertical"` | "horizontal" | option | Sets the Carousel orientation. |
| opts | `CarouselOptions["opts"]` | {} | option | Passes options to the underlying carousel engine. |
| plugins | `CarouselOptions["plugins"]` | - | option | Passes plugins to the underlying carousel engine. |
| setApi | `(api: CarouselInstance["api"]) => void` | - | callback | Receives the carousel API instance when it is ready. |
| autoInit | `boolean` | true | option | Initializes the carousel automatically when the page loads. |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel` | runtime | - | Marks the Root part so Starwind Runtime can find it. |
| `data-axis` | prop | - | Reflects the axis prop on the Root part. |
| `data-opts` | prop | - | Reflects the opts prop on the Root part. |
| `data-auto-init` | prop | - | Reflects the auto init prop on the Root part. |
#### Refs
| Part | Public |
| --- | --- |
| root | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel`, `role`, `aria-roledescription`, `data-axis`, `data-opts`, `data-auto-init` | The carousel root needs region semantics, orientation, options, and optional auto-init control before the Embla runtime attaches. |

### Viewport
The visible viewport for Carousel content.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel-viewport` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-viewport` | runtime | - | Marks the Viewport part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| viewport | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-viewport` | Embla needs a viewport element to measure visible slides. |

### Container
Groups the scrolling or moving content for Carousel.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel-container` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-container` | runtime | - | Marks the Container part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| container | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-container` | Embla uses the container as the translated slide rail. |

### Item
An interactive item inside the Carousel collection.
| Fact | Value |
| --- | --- |
| Default element | `div` |
| Discovery hook | `data-sw-carousel-item` |
| Role | `group` |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-item` | runtime | - | Marks the Item part so Starwind Runtime can find it. |
#### Refs
| Part | Public |
| --- | --- |
| item | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-item`, `role`, `aria-roledescription` | Carousel items need a stable marker and slide semantics for generated anatomy. |

### Previous
Moves Carousel to the previous item or slide.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-carousel-previous` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-previous` | runtime | - | Marks the Previous part so Starwind Runtime can find it. |
| `data-disabled` | state | - | Reflects the disabled state on the Previous part. |
#### Refs
| Part | Public |
| --- | --- |
| previous | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-previous`, `type`, `aria-disabled`, `data-disabled` | The previous control needs a discovery marker and safe button type before hydration. |

### Next
Moves Carousel to the next item or slide.
| Fact | Value |
| --- | --- |
| Default element | `button` |
| Discovery hook | `data-sw-carousel-next` |
| Role | - |
#### Data Attributes
| Attribute | Source | Value | Description |
| --- | --- | --- | --- |
| `data-sw-carousel-next` | runtime | - | Marks the Next part so Starwind Runtime can find it. |
| `data-disabled` | state | - | Reflects the disabled state on the Next part. |
#### Refs
| Part | Public |
| --- | --- |
| next | Yes |
#### Initial Markup
| Attributes | Reason |
| --- | --- |
| `data-sw-carousel-next`, `type`, `aria-disabled`, `data-disabled` | The next control needs a discovery marker and safe button type before hydration. |
## Runtime API
| Fact | Value |
| --- | --- |
| Factory | [`createCarousel`](/docs/runtime/#create-carousel) |
| Import | `@starwind-ui/runtime/carousel` |
| Root part | root |
| Option props | orientation, opts, plugins, setApi |
| Option lifecycles | orientation: refresh-required, opts: refresh-required, plugins: refresh-required, setApi: constructor-only |
## Related Styled Components
| Component | Relationship |
| --- | --- |
| [Carousel](/docs/components/carousel/) | Direct Primitive |
## Exports
| Group | Import | Exports |
| --- | --- | --- |
| Runtime | `@starwind-ui/runtime/carousel` | `createCarousel` |
| Astro Primitive | `@starwind-ui/astro/carousel` | `Carousel`, `CarouselRoot`, `CarouselViewport`, `CarouselContainer`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
| React Primitive | `@starwind-ui/react/carousel` | `Carousel`, `CarouselRoot`, `CarouselViewport`, `CarouselContainer`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` |
## Canonical Names
| Kind | Name |
| --- | --- |
| namespace | `Carousel` |
| runtime-factory | `createCarousel` |
| part | `Carousel.Root` |
| part | `Carousel.Viewport` |
| part | `Carousel.Container` |
| part | `Carousel.Item` |
| part | `Carousel.Previous` |
| part | `Carousel.Next` |