Skip to main content

Starwind UI v3.0 beta is now available! Read the migration guide

1
2
3
4
5

Installation

Framework Availability

Astro Available React Available

Carousel is available for Astro and React.

Usage

General Notes

The Carousel component is built on top of Embla Carousel and provides a responsive, touch-enabled carousel with smooth animations. It supports both horizontal and vertical orientations, multiple items per view, and various configuration options.

The essential components are Carousel, CarouselContent, and CarouselItem. The CarouselPrevious and CarouselNext components provide navigation controls.

Multiple Items

Show multiple items at once by using responsive basis classes on carousel items.

1
2
3
4
5

Carousels can be oriented vertically by setting the orientation prop.

1
2
3
4
5

Enable infinite looping with the loop option.

Loop

Plugins

Extend carousel functionality with Embla Carousel plugins. First install the plugin package, then manually initialize the Runtime primitive with createCarousel.

Info

You need to set autoInit={false} on the Carousel component, so that you can manually initialize it with your plugins and any additional options.

Runtime example adjustment

Plugin carousels disable styled auto-initialization and call createCarousel from @starwind-ui/astro/carousel, including reinitialization hooks for Astro navigation and dynamically added content.

API Reference

Styled Component API

These props are added or materially changed by the installed Astro styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Follow the Primitive and Runtime links for lower-level behavior props.

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
autoInit boolean
Description
Controls whether Runtime behavior initializes automatically.
Classification
Primitive override
Primitive prop
carousel.Root.autoInit
opts import("@starwind-ui/runtime").CarouselOptions["opts"]
Description
Provides options to the underlying carousel engine.
Classification
Primitive override
Primitive prop
carousel.Root.opts

Inherits button attributes.

Contains the following additional props:

Prop Type Default Toggle details
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "icon"
Description
Selects the component's visual size.
Classification
Styled variant
variant "default" | "primary" | "secondary" | "outline" | "ghost" | "info" | "success" | "warning" | "error" "outline"
Description
Selects the component's visual variant.
Classification
Styled variant

Inherits button attributes.

Contains the following additional props:

Prop Type Default Toggle details
size "sm" | "md" | "lg" | "icon-sm" | "icon" | "icon-lg" "icon"
Description
Selects the component's visual size.
Classification
Styled variant
variant "default" | "primary" | "secondary" | "outline" | "ghost" | "info" | "success" | "warning" | "error" "outline"
Description
Selects the component's visual variant.
Classification
Styled variant

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Carousel.

Primitive API

Runtime API

Carousel primitive
createCarousel from @starwind-ui/runtime/carousel

Changelog

v2.0.0

  • Rebuilt Carousel on Starwind Runtime for navigation, orientation, looping, and plugin lifecycle.
  • See the Carousel Primitive for the underlying unstyled anatomy and behavior API.