Docs·Carousel 004

Carousel 004

A spring-driven image gallery with a large draggable stage, compact expanding thumbnails, arrow controls, autoplay, and complete keyboard support.

Installation

$pnpm dlx shadcn@latest add @spiderui/carousel-004

Usage

API Reference

PropTypeDefault
itemsImages containing a stable id, source, and alt text.
Carousel004Item[]—
indexControlled active image index.
number—
defaultIndexInitial index when used uncontrolled.
number0
onIndexChangeCalled after the active image changes.
(index: number) => void—
loopWraps arrow, drag, and autoplay navigation.
booleanfalse
autoPlayAdvances automatically while interaction is idle.
booleanfalse
autoPlayIntervalMilliseconds between automatic changes.
number4000
pauseOnHoverPauses autoplay while the carousel is hovered.
booleantrue
aspectRatioCSS aspect ratio used by the main stage.
string"16 / 9"

Click on the icon in the top right of the example preview to view the source code for specific variants.

Keep in mind

This component is inspired by various open-source projects and patterns. Please verify licenses and implementation details before using in production.

Have any questions?
Contact on@ctrlcat0x
Pink poppies against a pale blue sky
Red flower in soft daylight
Large tropical green leaf
White flowers in a garden
Green houseplant leaves
Pink orchid in bloom

Showing image 1 of 6

import { Carousel004, type Carousel004Item } from "@/components/ui/carousel-004"
const images: Carousel004Item[] = [
  { id: "poppy", src: "/flowers/poppy.jpg", alt: "Pink poppy" },
  { id: "orchid", src: "/flowers/orchid.jpg", alt: "Pink orchid" },
  { id: "leaf", src: "/flowers/leaf.jpg", alt: "Tropical leaf" },
]

export function Gallery() {
  return <Carousel004 items={images} loop className="mx-auto max-w-5xl" />
}