Carousel

API reference for the Carousel component

A feature-rich carousel component with auto-slide, navigation controls, and indicators.

Import

import { Carousel } from "@zayne-labs/ui-react/ui/carousel";

Component Parts

Carousel.Root · component

The root container with state management

Carousel.ItemList · component

Container for carousel items with transition support

Carousel.Item · component

Individual carousel slide

Carousel.Controls · component

Navigation button container

Carousel.Button · component

Individual navigation button (prev/next)

Carousel.Caption · component

Overlay caption for slides

Carousel.IndicatorList · component

Container for slide indicators

Carousel.Indicator · component

Individual slide indicator button

Carousel.Root

The root container that manages carousel state and auto-slide functionality.

Props

as · React.ElementType · default: "div"

The element type to render as

images · ImagesType · required

Array of images to display. Can be an array of strings (URLs) or an array of objects with string properties

children · React.ReactNode · required

Child components

hasAutoSlide · boolean

Enable automatic slide transitions

autoSlideInterval · number

Interval in milliseconds between auto-slide transitions

shouldPauseOnHover · boolean

Pause auto-slide when hovering over the carousel

onSlideBtnClick · () => void

Callback fired when navigation buttons are clicked

classNames · object

Custom class names for carousel parts

• base?: string - Root container classes
• scrollContainer?: string - Scroll container classes

Data Attributes

• data-scope="carousel"
• data-part="content"
• data-slot="carousel-content"

Carousel.ItemList

Container for carousel items with smooth transition animations.

Props

className · string

CSS class names to apply to the item list

each · TArray

Optional array to iterate over. If not provided, uses the images array from Carousel.Root

children · React.ReactNode | RenderPropFn

Child components or render function

When using a render function, it receives:

• image - Current array item
• index - Current index
• array - Full array

Data Attributes

• data-scope="carousel"
• data-part="item-list"
• data-slot="carousel-item-list"

Carousel.Item

Individual carousel slide.

Props

className · string

CSS class names to apply to the item. Default styles include snap-center and full width

children · React.ReactNode

Content to display in the slide

Data Attributes

• data-scope="carousel"
• data-part="item"
• data-slot="carousel-item"

Carousel.Controls

Container for previous and next navigation buttons.

Props

classNames · object

Custom class names for control parts

• base?: string - Controls container classes
• iconContainer?: string - Icon wrapper classes
• defaultIcon?: string - Default chevron icon classes

icon · object

Custom icon configuration

Option 1: Single icon with rotation

• icon?: React.ReactElement - Custom icon element
• iconType: "prevIcon" | "nextIcon" - Which direction is the base icon

Option 2: Separate icons

• prev?: React.ReactElement - Previous button icon
• next?: React.ReactElement - Next button icon

Data Attributes

• data-scope="carousel"
• data-part="controls"
• data-slot="carousel-controls"

Carousel.Button

Individual navigation button for previous or next slide.

Props

variant · 'prev' | 'next' · required

Button direction

classNames · object

Custom class names for button parts

• base?: string - Button container classes
• iconContainer?: string - Icon wrapper classes
• defaultIcon?: string - Default chevron icon classes

icon · React.ReactElement

Custom icon element to display

Data Attributes

• data-scope="carousel"
• data-part="button"
• data-slot="carousel-button"

Carousel.Caption

Overlay caption element for slides.

Props

as · React.ElementType · default: "div"

The element type to render as

className · string

CSS class names to apply. Default includes absolute positioning and z-10

children · React.ReactNode

Caption content

Data Attributes

• data-scope="carousel"
• data-part="caption"
• data-slot="carousel-caption"

Carousel.IndicatorList

Container for slide indicator buttons.

Props

className · string

CSS class names to apply to the indicator list

each · TArray

Optional array to iterate over. If not provided, uses the images array from Carousel.Root

children · React.ReactNode | RenderPropFn

Child components or render function

When using a render function, it receives:

• image - Current array item
• index - Current index
• array - Full array

Data Attributes

• data-scope="carousel"
• data-part="indicator-list"
• data-slot="carousel-indicator-list"

Carousel.Indicator

Individual slide indicator button.

Props

currentIndex · number · required

The slide index this indicator represents

classNames · object

Custom class names for indicator parts

• base?: string - Indicator button classes
• isActive?: string - Active state classes

Data Attributes

• data-scope="carousel"
• data-part="indicator"
• data-slot="carousel-indicator"

Types

ImagesType

type ImagesType = Array<Record<string, string>> | string[];

CarouselStore

type CarouselStore<TImages extends ImagesType> = {
  currentSlide: number;
  maxSlide: number;
  images: TImages;
  actions: {
    goToNextSlide: () => void;
    goToPreviousSlide: () => void;
    goToSlide: (newValue: number) => void;
  };
};

CarouselStoreApi

import type { StoreApi } from "@zayne-labs/toolkit-core";

type CarouselStoreApi<TImages extends ImagesType> = StoreApi<CarouselStore<TImages>>;

Hooks

useCarouselStoreContext

Access the carousel store from within carousel components.

import { useCarouselStoreContext } from "@zayne-labs/ui-react/ui/carousel";

function CustomCarouselComponent() {
  const currentSlide = useCarouselStoreContext((state) => state.currentSlide);
  const { goToNextSlide } = useCarouselStoreContext((state) => state.actions);
  
  return <div>Current slide: {currentSlide}</div>;
}