# Carousel Primitive

Carousel is a Starwind Runtime primitive in the viewport-measurement contract family.
Astro and React share one semantic component API. React coordinates reactive state through controlled and default props plus callbacks. Astro renders initial state and coordinates later changes through DOM events and Runtime methods. Raw HTML uses Runtime attributes, DOM events, and imperative methods.
## 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>
```

### Vue
Use the Vue 3.5 beta adapter to render Carousel anatomy.
```vue
<script setup lang="ts">
import Carousel from "@starwind-ui/vue/carousel";
</script>

<template>
  <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>
</template>
```
## 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 | Framework Behavior |
| --- | --- | --- | --- | --- | --- |
| 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` |
## Changelog
### v1.0.0
- Promoted this Primitive's vendoring version to the stable 1.0.0 baseline. Its existing API and Runtime behavior carry forward from the previous release.
### v0.1.1
- Marked generated React Primitive files as client modules so vendored installs preserve client boundaries in React server frameworks.
### v0.1.0
- Introduced carousel navigation, orientation, looping, slide state, and plugin lifecycle coordination.