Loading…

Card Spread

beta

A stack of cards that fans into an arc, row, corner fan, stamp arc, cascade, dealt hand or wheel on hover, focus or click.

Display
2 files
2 npm packages
Accessibility notes

Playground

Installation

One command and the file is in your project, or copy it in by hand.

$pnpm dlx @dowel-ui/cli add card-spread

npm packages installed: class-variance-authority, radix-ui.

Usage

Imported from your own path — the file is yours, so this is an import like any other.

app/page.tsxTSX

import { CardSpread } from "@/components/ui/card-spread";

Examples

Every example the tests run, live and operable, side by side.

Default
Gallery
Stamp Arc
Link Cards
Right To Left

API

Generated from the component's own types, so a prop cannot appear here without existing.

<CardSpread>

Prop	Type	Default
`defaultOpen` Initial pinned-open state when uncontrolled.	`boolean`	`false`
`edge` Card edge for every item. Defaults to `stamp` for the stamp layout.	`"rounded" \| "stamp"`	—
`layout` How the cards fan out. `arc` with seven children is amicro's ARC (7 Cards).	`CardSpreadLayout`	`"arc"`
`onOpenChange` Called when the toggle (click, tap, Enter, Space or Escape) pins or unpins the spread.	`(open: boolean) => void`	—
`open` Controlled pinned-open state. Hover and focus still open it transiently.	`boolean`	—
`size`	`"sm" \| "md" \| "lg"`	`"md"`
`stagger` Milliseconds between one card starting to move and the next. Scaled for reduced motion.	`number`	`30`
`toggleLabel` Accessible name of the pin toggle a deck of non-interactive cards gets.	`string`	`"Spread cards"`
`trigger` What opens the spread. - `hover` (default): hover, keyboard focus anywhere inside, or pinned by the deck's toggle. - `click`: only the toggle. - `manual`: only the `open` prop; no toggle is rendered.	`CardSpreadTrigger`	`"hover"`

Plus every attribute of <div>.

<CardSpreadItem>

Prop	Type	Default
`edge`	`"rounded" \| "stamp"`	`"rounded"`
`asChild` Render the card surface as your own element — an `<a>` or `<button>` for a card that goes somewhere or does something.	`boolean`	—

Plus every attribute of <div>.

Accessibility

The deck is a role="group"; name it with aria-label or aria-labelledby. A deck of non-interactive cards gets a real toggle button (aria-pressed, named by `toggleLabel`, default "Spread cards") laid over the stack: it is the tab stop, Enter/Space/click/tap pin the spread open, and Escape closes it. It is a sibling of the cards, so every card's own content stays in the accessibility tree. A deck whose cards are links or buttons (via `asChild`) has no toggle and is reached through them. Keyboard focus anywhere inside opens the spread. Under reduced motion the layout still applies, instantly. In RTL the spread mirrors toward the inline start.

Quality

Measured from the source and its tests at build time.

All scores

10/10

checks passed

Tested — passes
axe assertion — passes
Keyboard tested — passes
Storybook examples — passes
Accessibility documented — passes
Semantic tokens only — passes
Motion from tokens — passes
className merged — passes
Visible focus — passes
No fixed widths — passes

Prop

Type

Default

defaultOpen

Initial pinned-open state when uncontrolled.

boolean

false

edge

Card edge for every item. Defaults to stamp for the stamp layout.

"rounded" | "stamp"

—

layout

How the cards fan out. arc with seven children is amicro's ARC (7 Cards).

CardSpreadLayout

"arc"

onOpenChange

Called when the toggle (click, tap, Enter, Space or Escape) pins or unpins the spread.

(open: boolean) => void

—

open

Controlled pinned-open state. Hover and focus still open it transiently.

boolean

—

size

"sm" | "md" | "lg"

"md"

stagger

Milliseconds between one card starting to move and the next. Scaled for reduced motion.

number

30

toggleLabel

Accessible name of the pin toggle a deck of non-interactive cards gets.

string

"Spread cards"

trigger

What opens the spread. - hover (default): hover, keyboard focus anywhere inside, or pinned by the deck's toggle. - click: only the toggle. - manual: only the open prop; no toggle is rendered.

CardSpreadTrigger

"hover"

Prop

Type

Default

edge

"rounded" | "stamp"

"rounded"

asChild

Render the card surface as your own element — an <a> or <button> for a card that goes somewhere or does something.

boolean

—