# Scramble text (goodtabs UI)

Characters scramble then settle in a wave, every width locked so nothing reflows.

## Install

```bash
npx shadcn@latest add https://ui.goodtabs.co/r/scramble-text.json
```

Or, with the @goodtabs namespace configured in components.json: `npx shadcn@latest add @goodtabs/scramble-text`

## Usage

```tsx
import { ScrambleText } from "@/components/ui/scramble-text"

<ScrambleText as="h2" className="font-mono text-5xl">Every width is locked</ScrambleText>
<ScrambleText trigger="hover" className="font-mono text-sm">Changelog</ScrambleText>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| children | `string` |  | The text, required and a plain string. |
| as | `"span" | "p" | "h1" | "h2" | "h3"` | `"span"` | The element to render. |
| trigger | `"view" | "hover"` | `"view"` | Run once on entering view, or on every hover and keyboard focus. |
| chars | `string` | `"abcdefghijklmnopqrstuvwxyz0123456789/_-+="` | Glyphs to scramble through. |
| hold | `number` | `0.5` | Seconds each character spends scrambling. |

## When to use

- Mono labels, version strings and short technical headings
- Links in a dense list, as a small reward on hover
- A status line that should feel like it just resolved

## When not to use

- Long paragraphs: it has to be read twice
- Anything people must read while it runs, such as an error
- Hero copy in a serif or display face, where the glyphs lose their shape

## Notes for agents

- GSAP installs from npm under GSAP's own licence. No GSAP code ships in this registry
- Mono reads best, but each character is locked to its settled width, so a proportional font does not reflow either
- A character the wave has not reached shows its real glyph, so the first frame equals the server HTML and there is no flash
- Inside a link or button the hover and focus listen on the whole control. Screen readers get the sr-only copy, the moving glyphs are aria-hidden
- chars is written as HTML by the plugin, so leave out < and &. Children must be a string

## The maths

- Step is min(0.03, 0.9 / n) seconds, so 30 characters take 0.87 plus the 0.5 hold, 1.37 seconds.
- Glyphs change every 0.05 / 0.7 = 71ms, 14 a second, because 60 a second reads as noise.
- Every cell's width is measured before it scrambles, so the line's width is the sum of settled widths on every frame.

Docs: https://ui.goodtabs.co/components/scramble-text