Card Shuffle Stack React component
A loose pile of photo cards you shuffle through: throw the top card aside and it tucks in under the stack, bring the bottom one back on top, with drag and flick physics, buttons, arrow keys, optional autoplay and a reduced-motion fallback.
About the Card Shuffle Stack component
Card Shuffle Stack shows a set of cards as a loose pile instead of a row. Throw the top card aside and it tucks itself in under the stack; go back and the bottom card slides out from under the pile and lands on top. It behaves like shuffling real cards, which makes paging through a team, a lookbook or a set of testimonials feel tactile.
You can drag and flick the top card, use the buttons underneath, or press the arrow keys. A counter and a row of thin indicators show where you are, and it can advance on its own if you turn on autoPlay.
When to use it
Use it for team members, featured products, testimonials or a small set of highlights, where one card at a time is the point and five to ten cards is the range.
For long lists or content people need to compare side by side, a grid or carousel is clearer.
Installation
Add the Card Shuffle Stack component to your project with the shadcn CLI. It lands in components/card-shuffle-stack.tsx as plain React + Tailwind CSS source you own and can edit.
npx shadcn@latest add @reactframe/card-shuffle-stackOr copy the source by hand and install its dependencies:
npm install motion lucide-react clsx tailwind-mergeProps
<CardShuffleStack /> accepts 10 props, all optional. It also accepts the usual <section> attributes, like className, style, id and aria-*, and passes them to its root element.
| Prop | Type | Default |
|---|---|---|
| cards | { id: string; image: string; imageAlt?: string; title: string; subtitle?: string; meta?: string }[] | CARDS |
| visibleDepth How many cards peek out behind the top one. | number | 3 |
| autoPlay Advance on its own every n ms; pauses on hover, focus and drag. 0 turns it off. | number | 0 |
| showControls | boolean | true |
| aspectRatio Width / height of each card. | number | 4 / 5 |
| radius | number | 20 |
| theme | "dark" | "light" | "dark" |
| label | string | "Team" |
| onChange | (card: ShuffleCard, index: number) => void | — |
| onCardClick | (card: ShuffleCard) => void | — |
- cards{ id: string; image: string; imageAlt?: string; title: string; subtitle?: string; meta?: string }[]Default: CARDS
- visibleDepth
How many cards peek out behind the top one.
numberDefault: 3 - autoPlay
Advance on its own every n ms; pauses on hover, focus and drag. 0 turns it off.
numberDefault: 0 - showControlsbooleanDefault: true
- aspectRatio
Width / height of each card.
numberDefault: 4 / 5 - radiusnumberDefault: 20
- theme"dark" | "light"Default: "dark"
- labelstringDefault: "Team"
- onChange(card: ShuffleCard, index: number) => void
- onCardClick(card: ShuffleCard) => void
npm dependencies
Installed for you by the shadcn CLI.
Card Shuffle Stack FAQ
- How do I throw a card?
- Drag the top card sideways past about a quarter of its width, or flick it quickly, and it flies out in that direction and tucks under the pile. A short drag springs back.
- Does it scroll on phones?
- Yes. Horizontal drags move the card, vertical swipes still scroll the page.
- Can it play on its own?
- Set autoPlay to a number of milliseconds. It pauses while the pointer is over the stack, while it has keyboard focus and while a card is being held, and never runs with reduced motion turned on.
- How many cards show in the pile?
- visibleDepth sets how many cards peek out behind the top one (3 by default). The rest wait hidden at the back.
