# Counter (counter)

> Number that counts up to a target.

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

## Install

```sh
npx shadcn@latest add @jbm/counter
```

Also installs @jbm/big, @jbm/motion-hooks (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/.
3. Install `remotion` and render inside a Remotion `<Composition>` or `<Player>`, not a plain React tree. Timing values are in seconds.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/counter.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/counter.tsx` | `src/jbm/motion/counter.tsx` | `@/jbm/motion/counter` |

## API

### `Counter` (component)

Renders a Big numeral that eases from 0 to `n`, rounded to whole numbers, on the Remotion timeline.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `n` | `number` | required | Target value; the count ends here and holds. |
| `at` | `number` | required | Start time in seconds from the start of the sequence. |
| `dur` | `number` | `0.8` | Seconds the count takes to reach `n`. |
| `size` | `number` | `140` | Font size in stage pixels, passed to Big. |
| `color` | `string` | `color.accent` | Text color; keep the one vermilion accent per composition. |

## Stage

Declared in stage pixels at the documented defaults.

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

One line of Big at size 140 with line-height 1.05. Height is size × 1.05; width follows the digit count of `n` (about 0.6 × size per digit).

## Examples

### Count to a key number

```tsx
import { Counter } from "@/jbm/motion/counter"

<Counter n={1024} at={0.2} dur={1.5} />
```

### Smaller, in ink, beside other text

```tsx
import { Counter } from "@/jbm/motion/counter"
import { color } from "@/jbm/lib/tokens"

<Counter n={42} at={1} size={96} color={color.ink} />
// Render inside a Remotion <Composition> or <Player>.
```

## QA

- Step to the first, middle, and last frames: 0 before `at`, an intermediate whole number mid-count, and exactly `n` at rest.
- In a host composition, check the widest value of `n` stays inside the safe area at the chosen size in both orientations (the gallery bench previews landscape only).
- Confirm only one element on the stage uses the accent color.

## Gallery preview cues

Cue times are seconds on the gallery preview's timeline, which renders the demo below; the Usage examples may use other timings. Map a cue to your own props by its place in the demo. The preview runs at 30 fps for 52 frames (0–51); see them side by side at https://jbm-ui.bns.studio/c/counter?view=strip, or open one frame with ?frame=<frame>.

```tsx
<Counter n={1024} at={0.2} dur={1.5} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Begin |  |
| 15 | 0.50 | Counting up | The number is mid-count (about halfway), easing toward 1024. |
| 51 | 1.70 | End |  |

## Related

Installs:

- [Big (big)](https://jbm-ui.bns.studio/catalog/big.md)
- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.md)

Imported in examples:

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