Carousel

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/carousel
• Markdown: https://ui.xzero.co.uk/components/carousel/markdown
• Registry item: https://mcp.xzero.co.uk/r/carousel.json
• Source file: registry/components/carousel/carousel.tsx
• Dependencies: motion, lucide-react
• Keywords: carousel, slider, gallery, react carousel, image slider, swipe carousel, autoplay carousel, accessible carousel, slideshow component

When to use

• A short set of peer items where neighbouring slides hint at more.
• Galleries browsed by drag, flick, trackpad swipe, or keys.
• Rotating highlights with a visible pause control, via interval.

When not to use

• Use cover-flow for a showpiece gallery and photo-grid to show everything at once.
• Use card-stack for deciding on items one at a time.

Installation

Register both Xzero UI namespaces in your project's components.json:

{
  "registries": {
    "@xzero-ui": "https://mcp.xzero.co.uk/r/{name}.json",
    "@xzero-ui-pro": "https://mcp.xzero.co.uk/r/pro/{name}.json"
  }
}

npx shadcn@4.23.0 add @xzero-ui/carousel

Install xzero-foundation once, and import @/components/xzero/foundation.css in your app root. No Xzero token is used by this snapshot. For sample portraits, photos, fonts, or logos, download https://mcp.xzero.co.uk/install-assets.mjs and run node xzero-install-assets.mjs <receiving-project>.

Usage

import { Carousel } from "@/components/xzero/carousel/carousel";

export function Suites() {
  return (
    <Carousel label="Harbour suites" interval={5000}>
      <img src="/suite-1.jpg" alt="Sea view suite" />
      <img src="/suite-2.jpg" alt="Garden suite" />
      <img src="/suite-3.jpg" alt="Loft suite" />
    </Carousel>
  );
}

API reference

Carousel

A centered slide row browsed by drag, flick, trackpad swipe, arrow keys, or pill indicators, with optional rotation.

Prop	Type	Default	Description
label (required)	string	–	Names the carousel for assistive technology.
children (required)	ReactNode	–	One child per slide.
index	number	–	Controlled active slide. Pair with onIndexChange.
defaultIndex	number	0	Initial slide when uncontrolled.
onIndexChange	(index: number) => void	–	Called when the active slide changes.
slideSize	string	"min(80cqw, 340px)"	Width of one slide as a CSS length.
slideLabel	(index: number, count: number) => string	"2 of 5"	Names each slide and its indicator.
interval	number	–	Milliseconds per slide. Adds a play control for rotation.
autoplay	boolean	false	Starts rotating on mount.
className	string	–	Class for the root section.

Keyboard interactions

Keys	Action
ArrowLeft / ArrowRight	Moves to the previous or next slide.
Home / End	Jumps to the first or last slide.
Tab	Moves between the slide area, play control, active indicator, and arrows.

Accessibility

• The root is a section with aria-roledescription="carousel"; slides are labelled tabpanels and the indicators a role="tablist".
• Inactive slides are inert, so their links are not focusable.
• Slide changes are announced in a polite live region.
• Rotation pauses on hover, keyboard focus, and drag, and has a visible pause control.

Motion

• Slides follow the finger and settle with momentum; neighbors shrink and dim with distance.
• The indicator stretches into a pill that tracks the slides, and drains to show rotation time.
• Reduced motion jumps between slides and disables rotation.

Responsive behavior

• Slides default to min(80cqw, 340px), so they size to the carousel's container rather than the viewport.
• Controls tighten when the container is under 340px.

Performance

• All slides stay mounted; inactive ones are inert, so keep the set short.
• Rotation pauses offscreen via IntersectionObserver and in hidden tabs via visibilitychange.

Notes for AI

• Use for a short set of peer items where neighbors should hint at more. Use cover-flow for a showpiece gallery and photo-grid to show everything at once.
• Give each slide a stable key if the list can change, and write a specific label.
• Keep autoplay off unless rotation is essential.

Related

• Cover flow: A depth rail of images you can throw, with soft grounded shadows and a quiet reflection.
• Photo grid: Pinch through zoom levels and open any photo straight from its cell.
• Card stack: Review a deck one card at a time, with a throw and an undo.
• Image compare: Drag a divider across two images to see what changed.

Guidance for AI tools

Carousel: Browse a row of slides by dragging, flicking, or arrowing through them. Follow the declared prop types and do not invent props. Keep keyboard access, reduced motion support, and both light and dark themes intact when adapting it.

Full library index: https://ui.xzero.co.uk/llms.txt