Cover flowPro

• Type: Component (special)
• Access: Xzero Pro
• Page: https://ui.xzero.co.uk/components/cover-flow
• Markdown: https://ui.xzero.co.uk/components/cover-flow/markdown
• Source file: registry/components/cover-flow/cover-flow.tsx
• Dependencies: motion
• Keywords: special, cover flow, carousel, react cover flow, coverflow carousel, 3d carousel, album carousel, image rail, itunes cover flow

When to use

• Six to twelve visual items where looking at one at a time is the point, such as albums, places, or collections.
• Showcase rails that should respond to drag, throw, and sideways trackpad scroll.

When not to use

• Use carousel for general slides or content cards.
• Use photo-grid or lightbox-gallery for a large library.
• Use depth-cards for about three rich choices that open into detail.

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-pro/cover-flow

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 { CoverFlow } from "@/components/xzero/cover-flow/cover-flow";

export function Hikes() {
  return (
    <CoverFlow
      label="Hikes for this fall"
      items={[
        { id: "ridge", title: "Ridge Loop", subtitle: "Mount Tam", meta: "8 km", image: "/hikes/ridge.jpg" },
        { id: "falls", title: "Cataract Falls", subtitle: "Marin", meta: "5 km", image: "/hikes/falls.jpg" },
      ]}
      onIndexChange={setIndex}
    />
  );
}

API reference

CoverFlow

A depth rail for browsing a short collection of images one at a time. The front card stands forward while the rest recede to either side, and each image drifts inside its frame as the rail moves.

Prop	Type	Default	Description
items (required)	{ id: string; title: string; subtitle?: string; meta?: string; image: string; imagePosition?: string; alt?: string }[]	–	Cards in order. alt defaults to the title. Generic: extra fields on your items are passed back to renderCaption.
label (required)	string	–	Accessible name of the carousel, such as "Hikes for this fall".
index	number	–	Controlled front card. Pair with onIndexChange.
defaultIndex	number	0	Initial front card when uncontrolled.
onIndexChange	(index: number) => void	–	Called when a different card settles in front, and while a drag passes over one.
renderCaption	(item: T, index: number) => ReactNode	–	Replaces the caption under the rail. It changes with the front card.
className	string	–	Extra class on the root.

Keyboard interactions

Keys	Action
ArrowLeft / ArrowRight	Steps one card while the rail has focus.
Home / End	Jumps to the first or last card.

Accessibility

• The root is labelled with aria-roledescription="carousel"; each card is a group with aria-roledescription="slide" and a label like "2 of 8: Ridge Loop".
• Cards away from the front are aria-hidden, and position ticks are labelled "Show <title>" with aria-current on the front one. Ticks are out of the tab order; the rail itself takes focus and handles the keys.
• The front card is announced in a polite live region.

Motion

• Drag or throw the rail and it lands on the card its momentum reaches, on a spring tuned to the release speed; a quick flick always moves at least one card. The ends rubber-band.
• Sideways trackpad scrolls move the rail directly, then settle on a card with the swipe's momentum. Clicking a card beside the front one brings it forward.
• Cards scale, dim, turn toward the center, and recede with distance while each image drifts inside its frame; the caption rises in from the direction of travel.
• Reduced motion jumps between cards, turns off the drift and the turn, and keeps short fades. A drag past 40px or one trackpad swipe steps one card.

Responsive behavior

• Cards size with the container at clamp(168px, 38cqw, 272px), so the rail scales from phones to wide sections.
• The stage uses touch-action pan-y, so vertical swipes still scroll the page and sideways ones move the rail.

Performance

• Every card is rendered, but cards far from the front get visibility hidden; keep the collection to a few dozen at most.
• Transforms and image drift run on motion values, and one ResizeObserver reads the card width.

Notes for AI

• Choose it for six to twelve visual items where one at a time is the point (places, albums, collections). Use carousel for general slides and photo-grid for a large library.
• Items are generic, so pass your own records and render extra fields through renderCaption.

Related

• Carousel: Browse a row of slides by dragging, flicking, or arrowing through them.
• Card stack: Review a deck one card at a time, with a throw and an undo.
• Photo grid: Pinch through zoom levels and open any photo straight from its cell.

Also in galleries

• Product gallery: A product gallery with a hover magnifier, gliding thumbnails, and color and size variants that crossfade photos.
• Lightbox gallery: A masonry grid where photos zoom from their slot into a viewer you can swipe, pinch, and drag away.

Guidance for AI tools

Cover flow: A depth rail of images you can throw, with soft grounded shadows and a quiet reflection. 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