# ScrollTextFill (scroll-text-fill)

> Scroll to bring text into focus, one character at a time. Keyboard scrolling, reversible progress, and reduced-motion support.

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

## Install

```sh
npx shadcn@latest add @jbm/scroll-text-fill
```

Also installs @jbm/text-fill, @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-text-fill.json, files[].content).

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

## API

### `ScrollTextFill` (component)

Self-contained, focusable scroll region that pins a TextFill in a sticky row and maps its own scroll position (0 at top, 1 at the bottom) to fill progress. Scrolling back rewinds; it never autoplays. Under reduced motion it renders the full text statically with no scroll region.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` | none | Class name on the TextFill span. |
| `style` | `CSSProperties` | none | Inline styles for the TextFill span; set fontSize here. |
| `text` | `string` | required | The sentence to fill; passed to TextFill. |
| `dimColor` | `string` | none | Color of characters not yet reached; passed to TextFill. |
| `accentColor` | `string` | none | Color of the leading wave; passed to TextFill. |
| `textColor` | `string` | none | Final color of settled characters; passed to TextFill. |
| `reducedMotion` | `boolean` | none | Overrides the system prefers-reduced-motion setting. True renders the complete text with auto height and no scrolling; undefined follows the system preference (and renders reduced on the server). |
| `height` | `number` | `320` | Height of the scroll viewport in stage pixels. Minimum 120; non-finite values fall back to 320. |
| `distance` | `number` | `640` | Extra scroll distance in pixels beyond the viewport; the whole fill happens over this travel. Minimum 1; non-finite values fall back to 640. |
| `label` | `string` | `"Scroll to fill the text"` | Accessible name of the scroll region. |

Also accepts Omit<TextFillProps, "progress">.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | fill | 320 |
| Vertical (1080×1920) | fill | 320 |

The region is width 100% and exactly `height` (default 320, minimum 120) stage pixels tall; the scrollable content inside is height + distance. With reduced motion the height becomes auto: the text plus 24px padding on each side, with a minimum of `height`.

## Examples

### Contained scroll fill

```tsx
import { ScrollTextFill } from "@/jbm/ui/scroll-text-fill"

<ScrollTextFill
  text="Una idea toma forma. Letra por letra."
  height={320}
  distance={640}
  style={{ fontSize: 40 }}
/>
// Self-contained scroll region; respects prefers-reduced-motion.
```

## QA

- Scroll the region from top to bottom and back: fill tracks scroll position in both directions and is complete exactly at the bottom.
- Focus the region with Tab and use ↓ / ↑ (and Page Down / Up): it scrolls and fills without scrolling the page (overscroll is contained).
- Enable prefers-reduced-motion (or pass reducedMotion): the full ink text renders statically, the region is not focusable, and there is no scroll.
- Check narrow screens: long text wraps inside the sticky row and stays vertically centered in the viewport.
- Change text or height after mount and confirm progress recomputes (a ResizeObserver re-measures).

## Related

Installs:

- [TextFill (text-fill)](https://jbm-ui.bns.studio/catalog/text-fill.md)
- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.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
