Carousel

A flexible slide carousel with arrow and dot navigation, keyboard support, autoplay, and drag-to-swipe. Use it to showcase features, images, or any repeating content.

Interactive Demo

Navigate with the arrows, dots, or by dragging a slide.

With autoplay

Enable autoplay to cycle through slides automatically.

With gap

Add breathing room between slides with the gap prop.

Custom icons

Pass any ReactNode to prevIcon and nextIcon to override the default chevrons.

Dots only

Hide the arrows with showArrows={false} and rely on dots or drag-to-swipe for navigation.

Arrows only

Or hide the dots with showDots={false} for a cleaner look.

Usage

import { Carousel } from "@mantleui/react/motion";
import { ArrowLeft, ArrowRight } from "lucide-react";

const slides = [
  <div key="1">Slide 1</div>,
  <div key="2">Slide 2</div>,
  <div key="3">Slide 3</div>,
];

// Basic
<Carousel slides={slides} defaultValue={0} loop />

// Autoplay
<Carousel slides={slides} autoplay interval={2500} />

// With gap
<Carousel slides={slides} gap={24} />

// Custom icons
<Carousel
  slides={slides}
  prevIcon={<ArrowLeft size={20} />}
  nextIcon={<ArrowRight size={20} />}
/>

// Hide arrows — dots only
<Carousel slides={slides} showArrows={false} />

// Hide dots — arrows only
<Carousel slides={slides} showDots={false} />

Props

Prop	Type	Default	Description
`slides`	`ReactNode[]`	—	The slides to render inside the carousel.
`value`	`number`	—	Controlled current slide index.
`defaultValue`	`number`	`0`	Default current slide index (uncontrolled).
`onValueChange`	`(index: number) => void`	—	Called when the current slide changes.
`autoplay`	`boolean`	`false`	Whether the carousel auto-advances.
`interval`	`number`	`3000`	Autoplay interval in ms.
`loop`	`boolean`	`true`	Whether to wrap around at edges.
`showArrows`	`boolean`	`true`	Whether to show prev/next arrow buttons.
`showDots`	`boolean`	`true`	Whether to show dot indicators.
`prevIcon`	`ReactNode`	—	Custom icon for the previous button. Defaults to a chevron-left.
`nextIcon`	`ReactNode`	—	Custom icon for the next button. Defaults to a chevron-right.
`gap`	`number`	`0`	Gap between slides in pixels.

slides

ReactNode[]

The slides to render inside the carousel.

value

number

Controlled current slide index.

defaultValue0

number

Default current slide index (uncontrolled).

onValueChange

(index: number) => void

Called when the current slide changes.

autoplayfalse

boolean

Whether the carousel auto-advances.

interval3000

number

Autoplay interval in ms.

looptrue

boolean

Whether to wrap around at edges.

showArrowstrue

boolean

Whether to show prev/next arrow buttons.

showDotstrue

boolean

Whether to show dot indicators.

prevIcon

ReactNode

Custom icon for the previous button. Defaults to a chevron-left.

nextIcon

ReactNode

Custom icon for the next button. Defaults to a chevron-right.

gap0

number

Gap between slides in pixels.