# ReplayButton (replay-button)

> Controlled replay icon whose arrow charges from tail to arrowhead as the host animation progresses, then unlocks.

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

## Install

```sh
npx shadcn@latest add @jbm/replay-button
```

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

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

## API

### `ReplayButton` (component)

Ink replay button with a 44px minimum hit area. While `charging`, the circular shaft draws on over the first 85% of `progress` and the arrowhead over the last 15%; clicks are ignored and the button stays focusable with aria-disabled. When not charging it shows the complete icon and calls `onReplay` on click. No internal timer and no Remotion dependency.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `progress` | `number` | required | Normalized progress of the host animation, 0–1. Clamped; non-finite values count as 0. Ignored (treated as 1) when `charging` is false. |
| `charging` | `boolean` | required | True while the host animation plays: shows the partial charge and blocks activation (aria-disabled, still focusable). False shows the complete icon and allows replay. |
| `onReplay` | `() => void` | required | Called on click only when neither `charging` nor `disabled` is set; restart your animation here. |
| `label` | `string` | `"Replay animation"` | Accessible name (aria-label) for the button. |
| `iconSize` | `number` | `26` | Width and height of the icon in pixels; the button adds 9px padding on each side. |

Also accepts Omit< React.ButtonHTMLAttributes<HTMLButtonElement>, "children" | "onClick" | "type" | "aria-label" >.

## Stage

Declared in stage pixels at the documented defaults.

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

iconSize 26 plus 9px padding on each side gives 44×44, which is also the enforced minimum hit area. Size grows with iconSize (iconSize + 18); the gallery demo uses iconSize 52 for a 70×70 button.

## Examples

### Wire to any animation

```tsx
import { ReplayButton } from "@/jbm/ui/replay-button"

<ReplayButton
  progress={progress} // 0–1 from your animation
  charging={isPlaying}
  onReplay={restartAnimation}
  label="Replay animation"
/>
```

### Larger icon

```tsx
import { ReplayButton } from "@/jbm/ui/replay-button"

<ReplayButton progress={1} charging={false} onReplay={() => player.seekTo(0)} iconSize={52} />
```

## QA

- Click replay and watch the charge: the shaft draws from its tail to the top-right, then the two arrowhead strokes draw in after 85% progress; at 100% the complete icon returns.
- While charging, click and press Enter/Space: nothing restarts, focus stays on the button, and it announces as disabled.
- Tab to the button and confirm the visible focus treatment on cream; check the 44×44 hit area at the default iconSize.
- Pass progress values below 0, above 1, and NaN while charging: the icon clamps instead of overdrawing or disappearing.

## Related

Installs:

- [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
