Carousel

free

Carousel presents ordered media or panels one at a time inside the current surface.

import Carousel from '@/components/ui/carousel';

const images = Array.from({ length: 5 }, (_, index) => ({
  src: `/img/thumbs/misc/img-${index + 1}.png`,

Installation

Add this component with the NateUI CLI.

npx nateui@latest add Carousel

pnpm dlx nateui@latest add Carousel

yarn dlx nateui@latest add Carousel

Examples

Basic

import Carousel from '@/components/ui/carousel';

const images = Array.from({ length: 5 }, (_, index) => ({
  src: `/img/thumbs/misc/img-${index + 1}.png`,

Sizes

import Carousel from '@/components/ui/carousel';

const images = Array.from({ length: 5 }, (_, index) => ({
  src: `/img/thumbs/misc/img-${index + 1}.png`,

Loop

import Carousel from '@/components/ui/carousel';

const images = Array.from({ length: 5 }, (_, index) => ({
  src: `/img/thumbs/misc/img-${index + 1}.png`,

Vertical

import Carousel from '@/components/ui/carousel';

const images = Array.from({ length: 5 }, (_, index) => ({
  src: `/img/thumbs/misc/img-${index + 1}.png`,

Trigger Placement

import Carousel from '@/components/ui/carousel';

const images = Array.from({ length: 3 }, (_, index) => ({
  src: `/img/thumbs/misc/img-${index + 1}.png`,

Gallery API

import { useState } from 'react';
import Carousel from '@/components/ui/carousel';
import type { CarouselApi } from '@/components/ui/carousel';

API

Carousel exposes a compound root with content, item, previous, and next subcomponents. The root accepts native div props.

Carousel

Prop	Description	Type	Default
`children`	Carousel content and controls, usually `Carousel.Content`, `Carousel.Item`, `Carousel.Previous`, and `Carousel.Next`.	`ReactNode`	-
`className`	Class names applied to the carousel root.	`string`	-
`orientation`	Direction used for keyboard navigation, drag movement, and item spacing.	`CarouselOrientation`	`'horizontal'`
`opts`	Carousel behavior options. The current implementation applies `loop` and `startIndex`.	`CarouselOptions`	`{}`
`setApi`	Receives the imperative carousel API for external controls and slide state.	`CarouselApiHandler`	-
`ref`	Ref forwarded to the carousel root.	`Ref<HTMLDivElement>`	-
`...nativeDivProps`	Native props for the carousel root `div`.	`NativeCarouselDivProps`	-

Carousel.Content

Prop	Description	Type	Default
`children`	Carousel items rendered inside the draggable content strip.	`ReactNode`	-
`className`	Class names applied to the moving content strip.	`string`	-
`ref`	Ref forwarded to the content strip.	`Ref<HTMLDivElement>`	-
`...nativeDivProps`	Native props for the content strip `div`.	`NativeCarouselContentProps`	-

Carousel.Item

Prop	Description	Type	Default
`children`	Slide content.	`ReactNode`	-
`className`	Class names applied to the slide wrapper. Use basis utilities for multi-slide layouts.	`string`	-
`ref`	Ref forwarded to the slide wrapper.	`Ref<HTMLDivElement>`	-
`...nativeDivProps`	Native props for the slide wrapper `div`.	`NativeCarouselItemProps`	-

Carousel.Previous And Carousel.Next

Prop	Description	Type	Default
`className`	Class names applied to the trigger button for placement or local layout.	`string`	-
`variant`	Button variant used by the trigger.	`ButtonVariant`	`'default'`
`size`	Button size used by the trigger.	`ControlSize`	`'sm'`
`disabled`	Override the trigger disabled state. If omitted, the trigger is disabled when it cannot scroll.	`boolean`	Derived from scroll state
`...buttonProps`	Button props except `icon`, `shape`, and `aria-label`, which the carousel trigger owns.	`CarouselTriggerProps`	-

Types

type CarouselOrientation = 'horizontal' | 'vertical';
 
type CarouselOptions = {
  align?: 'start' | 'center' | 'end';
  loop?: boolean;
  dragFree?: boolean;
  skipSnaps?: boolean;
  startIndex?: number;
};
 
type CarouselApi = {
  scrollPrev: () => void;
  scrollNext: () => void;
  canScrollPrev: boolean;
  canScrollNext: boolean;
  selectedIndex: number;
  scrollTo: (index: number) => void;
  scrollSnapCount: number;
};
 
type CarouselApiHandler = (api: CarouselApi) => void;
type ButtonVariant = 'solid' | 'subtle' | 'default' | 'ghost' | 'link';
type ControlSize = 'sm' | 'md' | 'lg';
type NativeCarouselDivProps = ComponentProps<'div'>;
type NativeCarouselContentProps = ComponentProps<'div'>;
type NativeCarouselItemProps = ComponentProps<'div'>;
type CarouselTriggerProps = Omit<
  ComponentPropsWithoutRef<typeof Button>,
  'icon' | 'shape' | 'aria-label'
>;