# ScrollStack (scroll-stack)

> Stack any React content as you scroll. Successive items scale into place while earlier ones fade. Page or contained scrolling, keyboard access, and a plain-list fallback.

- Entry: component
- Category: Interactive
- Preview capabilities: controls, scroll
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/scroll-stack
- JSON: https://jbm-ui.bns.studio/catalog/scroll-stack.json
- Registry item: https://jbm-ui.bns.studio/r/scroll-stack.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/scroll-stack
```

Also installs @jbm/tokens (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/scroll-stack.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/scroll-stack.tsx` | `src/jbm/ui/scroll-stack.tsx` | `@/jbm/ui/scroll-stack` |

## API

### `ScrollStack` (component)

A list region whose direct children become sticky items: each incoming item scales from 1.06 to 1 as it pins, and the item it covers shrinks toward `minScale` and fades out over the last 35% of its progress. Uses native scroll and sticky positioning (page or contained), never intercepts scroll, and scrolls a covered item back into view when keyboard focus reaches it. It falls back to a plain list under reduced motion, with fewer than two items, or when any item is taller than the viewport minus twice `top`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | required | Each direct child is one stack item; its content and styling stay yours. Keep backgrounds opaque for a solid stack; wrap related content in one element. |
| `height` | `number` | none | Omit to stack against page scrolling. Set a number for a self-contained, focusable scroll viewport of that many stage pixels (minimum 160; non-finite falls back to 480). |
| `distance` | `number` | `120` | Scroll distance in pixels between successive items while stacking (also the margin between them). Minimum 0; non-finite falls back to 120. The plain list uses a fixed 24px gap. |
| `top` | `number` | `24` | Sticky inset from the top of the viewport (or the contained region), in pixels; also the list's top padding. Minimum 0. |
| `minScale` | `number` | `0.9` | Scale of an item once fully covered, clamped to 0.5–1. |
| `reducedMotion` | `boolean` | none | True renders a plain list; false forces stacking. Undefined follows the system prefers-reduced-motion setting and updates when it changes. |
| `label` | `string` | `"Scroll through the stack"` | Accessible name of the region. |
| `className` | `string` | none | Class name on the outer region. |
| `style` | `CSSProperties` | none | Inline styles for the outer region, merged before height and overflow (those are controlled by `height`). |

## Stage

fluid: Width is 100% of the container. In page mode (height omitted) the height is the sum of the items plus `distance` between each, `top` padding, and a tail that lets the last item rest pinned. With `height` set the region is exactly that tall (minimum 160) and scrolls internally.

## Examples

### Contained stack of cards

```tsx
import { ScrollStack } from "@/jbm/ui/scroll-stack"
import { Card } from "@/jbm/ui/card" // install @jbm/card separately

<ScrollStack height={480} distance={120}>
  <Card>First idea</Card>
  <Card dark>Another idea</Card>
  <div style={{ background: "#fff", padding: 24 }}>Any content</div>
</ScrollStack>
// Omit height for page scrolling; avoid overflow ancestors in page mode.
```

## QA

- Scroll the contained demo from top to bottom and back: each card pins at the top inset, the covered card shrinks and fades fully before the next settles, and the last card rests without a gap or jump.
- Toggle Plain list: items render as an ordinary list with 24px gaps, no transforms, and full opacity; toggling back restores stacking.
- Tab into the covered cards' controls (the demo's button): the stack scrolls the focused item into view and it stays clickable.
- Resize to a narrow screen so an item is taller than the viewport: the component switches to the plain list (data-stack-mode="list").
- Check page mode separately (height omitted) inside a page without overflow ancestors; sticky positioning fails under overflow: hidden/auto parents.
- Enable prefers-reduced-motion with reducedMotion undefined: it falls back to the list live.

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)

Imported in examples:

- [Card (card)](https://jbm-ui.bns.studio/catalog/card.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
