# TextFill (text-fill)

> A controlled character sweep from muted text through vermilion into ink. Drive progress with a slider, scroll, or a video timeline.

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

## Install

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

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

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

## API

### `TextFill` (component)

Inline span that colors each grapheme by `progress`: characters ahead of the sweep stay dim, a short accent wave (about three characters) leads, and settled characters turn to text color. Pure React with no timers, browser globals, or Remotion; the full text is also rendered once in a visually hidden span for assistive technology, and the colored copy is aria-hidden.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `text` | `string` | required | The sentence to sweep. Split into words (whitespace preserved, words never break mid-word unless they overflow) and graphemes via Intl.Segmenter. |
| `progress` | `number` | required | Fill progress from 0 (all dim) to 1 (all text color). Clamped to 0–1; non-finite values render as 0. Drive from a slider, scroll position, or a timeline. |
| `dimColor` | `string` | `color.line` | Color of characters the sweep has not reached yet. |
| `accentColor` | `string` | `color.accent` | Color of the leading wave between dim and settled characters; keep the vermilion accent. |
| `textColor` | `string` | `color.ink` | Final color of settled characters, and of every character at progress 1. |
| `reducedMotion` | `boolean` | `false` | When true, renders the complete text in textColor regardless of progress. |
| `style` | `CSSProperties` | none | Inline styles merged over the defaults (Geist sans, weight 800, line-height 1.15, pre-wrap); set fontSize here. |
| `className` | `string` | none | Class name on the outer span. |

## Stage

fluid: Inline text: width follows the container and height follows the wrapped lines at the inherited font size × 1.15 line-height. Nothing is fixed; set fontSize through style or a parent.

## Examples

### Half-filled sentence

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

<TextFill text="Una idea toma forma." progress={0.5} style={{ fontSize: 40 }} />
// progress: 0–1, controlled; no internal timer.
```

### Drive it from a Remotion timeline

```tsx
import { TextFill } from "@/jbm/ui/text-fill"
import { useProgress } from "@/jbm/motion/hooks" // install @jbm/motion-hooks separately

// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.
export function FillingText() {
  const progress = useProgress(0.2, 1, 2)
  return <TextFill text="Letra por letra." progress={progress} style={{ fontSize: 72 }} />
}
```

## QA

- Drag the progress slider through 0, about 0.5, and 1: all dim at 0, a dim → vermilion → ink gradient near the sweep front mid-way, and solid ink at 1 with no lingering accent.
- Check wrapping on a narrow screen: words stay whole and whitespace is preserved; very long words wrap anywhere instead of overflowing.
- With a screen reader, the sentence is read once from the hidden copy, not character by character.
- Set reducedMotion and confirm the full ink text renders at any progress.
- Try text with emoji or combining marks; each grapheme should color as one unit.

## Related

Installs:

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

Installed by:

- [ScrollTextFill (scroll-text-fill)](https://jbm-ui.bns.studio/catalog/scroll-text-fill.md)
- [Burbuja (burbuja)](https://jbm-ui.bns.studio/catalog/burbuja.md)

Imported in examples:

- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.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
