Card stack

• Type: Component (data)
• Access: Free, open source
• Page: https://ui.xzero.co.uk/components/card-stack
• Markdown: https://ui.xzero.co.uk/components/card-stack/markdown
• Registry item: https://mcp.xzero.co.uk/r/card-stack.json
• Source file: registry/components/card-stack/card-stack.tsx
• Dependencies: motion, lucide-react
• Keywords: gesture, motion, triage, react card stack, swipe cards, tinder swipe, swipeable card deck, card triage, swipe left right

When to use

• One-by-one triage such as shortlisting, review queues, or onboarding picks.
• Decks where swiping left or right should be undoable.

When not to use

• Use a list or sortable-data-table when people compare items side by side.
• Use carousel to browse items without deciding.
• Use swipe-actions for quick actions on rows in a list.

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/card-stack

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 { CardStack } from "@/components/xzero/card-stack/card-stack";

const cities = [{ id: "lis", name: "Lisbon" }, { id: "osl", name: "Oslo" }, { id: "kyo", name: "Kyoto" }];

export function Shortlist() {
  return (
    <CardStack
      items={cities}
      getKey={city => city.id}
      getLabel={city => city.name}
      renderCard={city => <h3>{city.name}</h3>}
      labels={{ left: "Skip", right: "Shortlist" }}
      onDecide={(city, decision) => save(city.id, decision)}
    />
  );
}

API reference

CardStack

A deck reviewed one card at a time by swiping left or right, with buttons, undo, and reset.

Prop	Type	Default	Description
items (required)	T[]	–	Cards in order.
getKey (required)	(item: T) => string	–	Stable key per item.
getLabel (required)	(item: T) => string	–	Short name for labels and announcements, such as "Lisbon".
renderCard (required)	(item: T) => ReactNode	–	Card content.
onDecide	(item: T, decision: "left" | "right") => void	–	Called when a card is swiped or decided by button or key.
onUndo	(item: T, decision: "left" | "right") => void	–	Called when the last decision is undone.
onReset	() => void	–	Called when all cards come back.
labels	{ left: string; right: string }	{ left: "Pass", right: "Keep" }	Action names on the buttons and drag stamps.
outcomes	{ left: string; right: string }	–	Past tense of each action for announcements, such as "skipped".
label	string	"Cards"	Accessible name for the stack.
renderEmpty	(reset: () => void) => ReactNode	–	Shown once every card is decided. Defaults to a Start over button.
className	string	–	Class for the root.

Keyboard interactions

Keys	Action
ArrowLeft / ArrowRight	Decides the top card left or right when the stack is focused.
Backspace / Cmd+Z / Ctrl+Z	Undoes the last decision.

Accessibility

• The stage is a focusable role="group" with aria-roledescription="card stack" and a hidden hint describing drag and keys.
• Each card is labelled like "Lisbon, 1 of 3".
• Decisions, undo, and reset are announced in a polite status region.
• Buttons mirror every gesture, so swiping is never required.

Motion

• The top card follows the drag with tilt and stamps; a flick or far drag throws it off with its velocity.
• Cards beneath rise into place, and undo flies a card back from where it left.
• Reduced motion fades cards out and in at home without travel.

Responsive behavior

• The stage is min(100%, 20rem) wide; below 26rem the cards get shorter, and below 22.5rem Undo becomes icon-only.
• Cards use touch-action pan-y, so vertical swipes still scroll the page.

Performance

• Only the top four cards render in the stage, however long the deck.
• Drag and throw run on motion values without per-frame React updates.

Notes for AI

• Use for one-by-one triage: shortlisting, review queues, onboarding picks. Use a list or sortable-data-table when people compare items side by side.
• Persist decisions from onDecide and reverse them in onUndo.

Related

• Swipe actions: Reveal row actions with a swipe, or from the same actions in a menu.
• Carousel: Browse a row of slides by dragging, flicking, or arrowing through them.
• Wallet stack: Fan a stack of cards and lift one out to see its activity.

Also in media

• Image compare: Drag a divider across two images to see what changed.

Guidance for AI tools

Card stack: Review a deck one card at a time, with a throw and an undo. 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