On this page

Carousel Primitive

Carousel is a Starwind Runtime primitive in the viewport-measurement contract family. Astro, React, Vue, and Svelte components use the same underlying interactions. Each framework has its own way to read and update state. See the examples and your installed package’s types for the available props and events. Plain HTML uses DOM events and Runtime methods.

Anatomy

Use the Astro primitive adapter to render Carousel anatomy with the Runtime wiring included.

---
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>

Use the React primitive adapter when Carousel state participates in React rendering.

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>
  );
}

Use the Vue components to build Carousel.

<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>

Render the Carousel data-sw-* contract yourself, then initialize createCarousel.

<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.

Default element: div
Discovery hook: data-sw-carousel
Role: region

Props

Prop Type Default

orientation "horizontal" | "vertical" "horizontal"

Description: Sets the Carousel orientation.
Kind: option
Targets: root
Full type: "horizontal" | "vertical"

opts CarouselOptions["opts"] {}

Description: Passes options to the underlying carousel engine.
Kind: option
Targets: root
Full type: CarouselOptions["opts"]

plugins CarouselOptions["plugins"] -

Description: Passes plugins to the underlying carousel engine.
Kind: option
Targets: root
Full type: CarouselOptions["plugins"]

setApi (api: CarouselInstance["api"]) => void -

Description: Receives the carousel API instance when it is ready.
Kind: callback
Targets: root
Full type: (api: CarouselInstance["api"]) => void

autoInit boolean true

Description: Initializes the carousel automatically when the page loads.
Kind: option
Targets: root
Full type: boolean

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-carousel - Marks the Root part so Starwind Runtime can find it.

Metadata

Attribute Value Description

data-axis - Reflects the axis prop on the Root part.

data-opts - Reflects the opts prop on the Root part.

data-auto-init - Reflects the auto init prop on the Root part.

Viewport

The visible viewport for Carousel content.

Default element: div
Discovery hook: data-sw-carousel-viewport
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-carousel-viewport - Marks the Viewport part so Starwind Runtime can find it.

Container

Groups the scrolling or moving content for Carousel.

Default element: div
Discovery hook: data-sw-carousel-container
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-carousel-container - Marks the Container part so Starwind Runtime can find it.

Item

An interactive item inside the Carousel collection.

Default element: div
Discovery hook: data-sw-carousel-item
Role: group

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-carousel-item - Marks the Item part so Starwind Runtime can find it.

Moves Carousel to the previous item or slide.

Default element: button
Discovery hook: data-sw-carousel-previous
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-carousel-previous - Marks the Previous part so Starwind Runtime can find it.

State

Attribute Value Description

data-disabled - Reflects the disabled state on the Previous part.

Moves Carousel to the next item or slide.

Default element: button
Discovery hook: data-sw-carousel-next
Role: -

Data Attributes

Runtime hooks

Attribute Value Description

data-sw-carousel-next - Marks the Next part so Starwind Runtime can find it.

State

Attribute Value Description

data-disabled - Reflects the disabled state on the Next part.

Runtime API

Factory: createCarousel
Import: @starwind-ui/runtime/carousel
Root hook: root data-sw-carousel
Option props: orientation, opts, plugins, setApi

Option Lifecycles

Option	Lifecycle
orientation	refresh-required
opts	refresh-required
plugins	refresh-required
setApi	constructor-only

Component Relationship

Carousel Direct primitive

Changelog

View version history v1.0.1 4 releases

v1.0.1

Maintenance update with no changes to the public API.
Reduced repeated JavaScript when Astro Carousel is used with other Starwind components.

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.

Layer Metadata

Carousel Primitive uses createCarousel. Styled components: Carousel.

primitive Carousel Primitive Carousel Primitive uses createCarousel. Styled components: Carousel. Runtime primitive Primitive adapter Astro Primitive adapters React Primitive adapters carousel Carousel Viewport Measurement Primitives that measure and synchronize scrollable viewport UI. /docs/primitives/carousel/ createCarousel @starwind-ui/runtime/carousel /docs/runtime/#create-carousel root orientation opts plugins setApi raw-html astro react solid svelte vue HTML Astro React Solid Svelte Vue Raw HTML Render the Carousel data-sw-* contract yourself, then initialize createCarousel. html Use the Astro primitive adapter to render Carousel anatomy with the Runtime wiring included. Use the React primitive adapter when Carousel state participates in React rendering. tsx Use the Vue components to build Carousel. div data-sw-carousel region "horizontal" | "vertical" Sets the Carousel orientation. CarouselOptions["opts"] Passes options to the underlying carousel engine. CarouselOptions["plugins"] Passes plugins to the underlying carousel engine. (api: CarouselInstance["api"]) => void Receives the carousel API instance when it is ready. autoInit boolean Initializes the carousel automatically when the page loads. runtime Marks the Root part so Starwind Runtime can find it. data-axis prop Reflects the axis prop on the Root part. data-opts Reflects the opts prop on the Root part. data-auto-init Reflects the auto init prop on the Root part. viewport data-sw-carousel-viewport Marks the Viewport part so Starwind Runtime can find it. container data-sw-carousel-container Marks the Container part so Starwind Runtime can find it. item data-sw-carousel-item group Marks the Item part so Starwind Runtime can find it. previous button data-sw-carousel-previous Marks the Previous part so Starwind Runtime can find it. data-disabled state Reflects the disabled state on the Previous part. next data-sw-carousel-next Marks the Next part so Starwind Runtime can find it. Reflects the disabled state on the Next part. Root role aria-roledescription Viewport Container Item Previous type aria-disabled Next @starwind-ui/astro @starwind-ui/astro/carousel Render static carousel anatomy and self-initialize unless autoInit is false; plugin use remains an imperative createCarousel escape hatch. @starwind-ui/react @starwind-ui/react/carousel Create the runtime controller once, pass opts/plugins/setApi at construction, and reInit when orientation, opts, or plugins change. @starwind-ui/vue @starwind-ui/vue/carousel @starwind-ui/svelte @starwind-ui/svelte/carousel /docs/components/carousel/ Direct primitive direct-primitive Styled component Carousel

Carousel Primitive

Anatomy

API Reference

Root

Props

Data Attributes

Runtime hooks

Metadata

Viewport

Data Attributes

Runtime hooks

Container

Data Attributes

Runtime hooks

Item

Data Attributes

Runtime hooks

Previous

Data Attributes

Runtime hooks

State

Next

Data Attributes

Runtime hooks

State

Runtime API

Option Lifecycles

Related Styled Components

Changelog

v1.0.1

v1.0.0

v0.1.1

v0.1.0