Skip to content
Pinky UI

Stack to Grid

One collection in two arrangements — a pile that unpacks into a grid.

  • grids
  • shared layout
  • expand
  • signature
  • transition
6 items · stack

  • Motion

  • Surfaces

  • Light

  • Depth

  • Layout

  • Controls

Usage

usage
import { StackGrid } from "@pinky-ui/layouts";

<StackGrid defaultMode="stack" columns={3}>
  {items.map((item) => (
    <SpotlightCard key={item.id}>{item.title}</SpotlightCard>
  ))}
</StackGrid>

Props

PropTypeDefaultDescription
mode"stack" | "grid"—Controlled mode. Omit to let the component own it.
defaultMode"stack" | "grid""stack"Initial arrangement.
onModeChange(mode) => void—Called when the arrangement changes.
columnsnumber3Grid columns when spread out.
offsetnumber14Offset between stacked cards, in px.
controlsbooleantrueRenders the built-in toggle.

Accessibility

  • Both states are the same list in the same DOM order.
  • The toggle is a real button with aria-pressed.
  • Nothing is removed from the accessibility tree in either arrangement.

Performance

  • Shared layout animation measures each card once per transition, not per frame.
  • Only the top five cards render offset in the stack; the rest sit hidden behind them.

Reduced motion

With prefers-reduced-motion: reduce, the two arrangements swap instantly. No cards fly across the screen.

When to use

  • Showing that a small collection has more inside it
  • Onboarding or feature walkthroughs
  • A section that should reward one click

When not to use

  • Primary navigation of a large catalogue
  • Anywhere users need to scan everything immediately — start in grid mode instead

Skill

Purpose

Shows that a small collection has more inside it. Cards sit as a pile, then unpack into a grid — the same elements moving, not one view replaced by another.

Good for

  • revealing a curated set from a compact starting point
  • onboarding and feature walkthroughs
  • a section that should reward one click

Avoid for

  • primary navigation of a large catalogue
  • anywhere users must scan everything immediately — start in grid mode instead

How many items

Three to twelve. A stack cannot suggest what it contains past a dozen, and the grid it becomes gets unwieldy.

Mobile

One or two columns in grid mode. The stack state is unchanged and works well on narrow screens, which makes this a good mobile-first pattern.

Motion intensity

The default spring is soft and should stay there — this is a large spatial change, and overshoot on a dozen cards at once is chaos.

Accessibility

  • Both arrangements are the same list in the same DOM order.
  • The toggle is a real button with aria-pressed.
  • Nothing leaves the accessibility tree in either state.

Performance

The shared layout animation measures each card once per transition, never per frame. Only the top five cards render offset in the stack; the rest sit behind them. Keep card content light — every card is mounted in both states.

Composes with

Spotlight Card is the best partner: calm surfaces let the arrangement itself be the interaction. Avoid Jelly or Liquid cards here — during the transition you would have twelve surfaces animating for two different reasons.

Open this skill on its own page