# Word swap (goodtabs UI)

One word in a sentence swaps through a list, and the sentence never reflows.

## Install

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

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

## Usage

```tsx
import { WordSwap } from "@/components/ui/word-swap"

<h2>
  Interfaces that feel <WordSwap words={["calm", "quick", "honest"]} />
</h2>
```

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| words | `string[]` |  | The words to walk through, required. The first is the still state and the accessible text. |
| hold | `number` | `1.8` | Seconds each word rests. |
| duration | `number` | `0.6` | Seconds a swap takes. |

## When to use

- A hero sentence with several true endings
- A word at the end of a line, where the slot's spare width falls off the edge
- A few short words of similar length

## When not to use

- In the middle of a centred line: the slot keeps the longest word's width
- Words people must read to act
- More than five or six words, nobody waits for them

## Notes for agents

- GSAP installs from npm under GSAP's own licence. No GSAP code ships in this registry
- It is an inline span, so it sits inside your own heading and takes on its type. Every word shares one grid cell, so the slot holds the longest word's width before any script runs
- Screen readers get the sentence with the first word, the visible words are aria-hidden and aria-live stays off
- It pauses off screen, on hover and on keyboard focus, which is why it is a tab stop. A swap in progress finishes first, so a word is never left half way
- Under reduced motion only the first word shows. Words must be unique, they are the React keys

## The maths

- The slot is a one-cell grid, so its width is the widest word with no measuring.
- A word travels 140 percent of its height: 100 for its line, 16 for the mask's bleed and 24 for the descender.
- A full cycle is n × (hold + duration), 9.6 seconds for four words at the defaults.

Docs: https://ui.goodtabs.co/components/word-swap