@lesetong/cardstack

A fanned card deck with hover fan, spring swipe-to-flip and progress dots, built on motion. Available on npm.

Inspired by HyperOS 4

Features

• Hover fan — cards 2/3 tilt out behind the front card with progressive blur
• Bidirectional flip — drag up for the next card or down for the previous card; horizontal-only releases restore without changing the index
• Force-coupled deck — vertical pulls give the second card a subtle same-direction follow; downward pulls also counterload the backmost card
• Progress dots — white dot indicator on the right tracks your position in the deck
• Controlled rolling — optionally animate parent-driven index jumps through every intermediate card
• Configurable — per-card CardPose (tilt / origin / blur), size variant, radius
• Fast — three cards at rest, with a short-lived maximum of five during overlapping gestures

Install

npm install @lesetong/cardstack
# or
pnpm add @lesetong/cardstack

Requires react and motion as peer dependencies.

import { CardStack } from '@lesetong/cardstack'
import '@lesetong/cardstack/style.css'

<CardStack
  cards={[<img src="a.jpg" alt="" />, <img src="b.jpg" alt="" />]}
  size="large"
  second={{ rotate: 6 }}
  third={{ rotate: -6, blur: 3 }}
/>

Controlled usage:

import { useState } from 'react'

const [index, setIndex] = useState(0)

<CardStack
  cards={cards}
  index={index}
  animateIndexChanges
  indexDirection="auto"
  onChange={setIndex}
/>

Passing index makes the component controlled. Parent-driven index changes synchronize immediately by default. Enable animateIndexChanges to roll through every intermediate card. indexDirection="auto" takes the shortest circular route; use "forward" or "backward" to force a route. Intermediate visual steps do not call onChange. Omit index for uncontrolled usage; use defaultIndex to choose the initial card.

Gestures

Drag up       → next card
Drag down     → previous card
Drag sideways → restore current card

The front card follows both axes, but only projected vertical movement changes the index. During vertical pulls, the visible second card follows the same x/y direction at a much smaller amplitude. A downward pull also keeps the backmost card in its original z-index and counterloads it. Releasing a committed backward gesture promotes the backmost card and returns the dragged card to the center as the new second slot.

Props

Prop	Type	Default	Description
cards	ReactNode[]	—	Card contents, front to back
index	number	—	Controlled front-card index (0-based)
defaultIndex	number	0	Initial index for uncontrolled usage
animateIndexChanges	boolean	false	Roll through intermediate cards when the parent changes index
indexDirection	"auto" | "forward" | "backward"	"auto"	Route used for animated index changes; auto chooses the shortest circular path
onChange	(index: number) => void	—	Called after a user gesture successfully flips a card
size	"large" | "small"	"large"	Variant (dimensions, origins, dots)
width / height	number	per size	Deck size (px)
radius	number	14 / 12	Card corner radius (px)
second / third	CardPose	—	Pose overrides: { rotate?, origin?, blur? }

Demo

Live Storybook: https://leset0ng.github.io/card-stack/

Dev

nub run dev              # storybook
nub run build            # library build
nub run typecheck        # tsc --noEmit
nub run build-storybook  # static docs site