Ring Carousel 3D

ProNew

Cards arranged on a 3D ring that turns to the active card, with drag, click, arrow keys, buttons and autoplay.

Customize

This item has no props to tune. Use the lens above to change theme, density, direction and more.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/ring-carousel-3d

Usage

Props

Prop	Type	Default	Description
`items`	`{ title: string; description?: string; image?: string; color?: string }[]`	`-`	Cards on the ring. Images must be same-origin or served with CORS.
`interval`	`number`	`4000`	Autoplay delay in ms; `0` turns autoplay off. Pauses on hover, focus and for reduced motion.
`colors`	`string[]`	theme	Card colours used in turn when an item has no `color`.
`index`	`number`	`-`	Controlled active index.
`onIndexChange`	`(index: number) => void`	`-`	Called when the active card changes.
`label`	`string`	`"Featured items"`	Accessible name of the carousel region.
`controls`	`boolean`	`true`	Show the previous and next buttons.
`fallback`	`ReactNode`	gradient	Static frame shown while loading and when WebGL is unavailable.
`className`	`string`	`-`	Classes for the outer element.

Keyboard

The ring is a focusable group: ← and → turn it, and a polite live region announces the active card. Card text is drawn into the 3D scene, so the same text is always available in the DOM as well.

Performance and accessibility

three.js loads only when the component comes within 200px of the viewport, in its own chunk, so pages that do not show it never download it.
Rendering pauses while it is offscreen or the tab is hidden, and the pixel ratio is capped at 2.
With prefers-reduced-motion: reduce it renders a single still frame.
Without WebGL, or before the scene loads, a static gradient is shown instead.
Colours come from your theme's CSS variables and update when the theme changes.

Guide and examples

Installation


pnpm dlx shadcn@latest add @tealmac-pro/ring-carousel-3d

Usage

Props

Prop	Type	Default	Description
`items`	`{ title: string; description?: string; image?: string; color?: string }[]`	`-`	Cards on the ring. Images must be same-origin or served with CORS.
`interval`	`number`	`4000`	Autoplay delay in ms; `0` turns autoplay off. Pauses on hover, focus and for reduced motion.
`colors`	`string[]`	theme	Card colours used in turn when an item has no `color`.
`index`	`number`	`-`	Controlled active index.
`onIndexChange`	`(index: number) => void`	`-`	Called when the active card changes.
`label`	`string`	`"Featured items"`	Accessible name of the carousel region.
`controls`	`boolean`	`true`	Show the previous and next buttons.
`fallback`	`ReactNode`	gradient	Static frame shown while loading and when WebGL is unavailable.
`className`	`string`	`-`	Classes for the outer element.

Keyboard

Performance and accessibility

three.js loads only when the component comes within 200px of the viewport, in its own chunk, so pages that do not show it never download it.
Rendering pauses while it is offscreen or the tab is hidden, and the pixel ratio is capped at 2.
With prefers-reduced-motion: reduce it renders a single still frame.
Without WebGL, or before the scene loads, a static gradient is shown instead.
Colours come from your theme's CSS variables and update when the theme changes.