# MotionHooks (motion-hooks)

> Remotion timing hooks in seconds: elapsed time, a spring entrance, a cubic-out fade, and an eased progress value.

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

## Install

```sh
npx shadcn@latest add @jbm/motion-hooks
```

## 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/motion-hooks.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/hooks.ts` | `src/jbm/motion/hooks.ts` | `@/jbm/motion/hooks` |

## API

### `useSec` (hook)

Seconds elapsed since the start of the enclosing Remotion Sequence (current frame ÷ fps).

Returns: Elapsed seconds as a number; fractional between frames.

### `useIn` (hook)

Spring entrance that starts at `startSec` (rounded to the nearest frame) with mass 0.8. Stays 0 before the start and settles near 1; it can overshoot 1 slightly while settling.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `startSec` | `number` | required | Start time in seconds relative to the enclosing Sequence. |
| `opts` | `{ damping?: number; stiffness?: number }` | none | Optional spring config: `damping` (default 14) and `stiffness` (default 120). Lower damping bounces more. |

Returns: Spring value from 0 toward 1, for opacity, scale, or translate progress.

### `useFade` (hook)

Cubic-out interpolation from 0 to 1 over `dur` seconds starting at `startSec`, clamped at both ends.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `startSec` | `number` | required | Start time in seconds relative to the enclosing Sequence. |
| `dur` | `number` | `0.4` | Fade length in seconds. |

Returns: Opacity-style value clamped to 0–1.

### `useProgress` (hook)

Cubic-out interpolation from 0 to `target` over `dur` seconds starting at `startSec`, clamped at both ends. Use for bar fills, counters, and draw-on strokes.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `startSec` | `number` | required | Start time in seconds relative to the enclosing Sequence. |
| `target` | `number` | `1` | Value reached at `startSec + dur` and held afterwards (e.g. 1, 100, or a probability). |
| `dur` | `number` | `0.7` | Seconds taken to reach `target`. |

Returns: Number between 0 and `target`.

## Stage

n/a: Hooks only; they render nothing. The gallery preview is a demo component built on them.

## Examples

### Entrance, fade, and a counting value

```tsx
import { useSec, useIn, useFade, useProgress } from "@/jbm/motion/hooks"

// Render inside a Remotion <Composition> or <Player>: hooks run in the component body.
export function TimelineReadout() {
  const seconds = useSec()
  const entrance = useIn(0.2)
  const opacity = useFade(0.2)
  const progress = useProgress(0.2, 100, 1.5)
  return (
    <div style={{ opacity, transform: `translateY(${(1 - entrance) * 30}px)` }}>
      {progress.toFixed(0)}% at {seconds.toFixed(2)}s
    </div>
  )
}
```

## QA

- Step to the first frame, the middle of the 1.5 s window, and the last frame: the percentage reads 0, an intermediate value, then exactly 100; useSec matches frame ÷ fps.
- Check that times are relative to the enclosing Sequence: a component inside a Sequence that starts later still enters at its own `startSec`.
- When changing spring defaults, re-check every consumer (Pop, ProbBar, RebuildScreens, Catalog) and the gallery preview durations measured from the same spring config.

## 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/motion-hooks?view=strip, or open one frame with ?frame=<frame>.

```tsx
const entrance = useIn(0.2)
const opacity = useFade(0.2)
const progress = useProgress(0.2, 100, 1.5)
// A Big number shows progress.toFixed(0) + "%", fading and rising in with opacity and entrance.
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Empty stage |  |
| 15 | 0.50 | Counting up | The percentage is mid-count while the block is still rising into place. |
| 51 | 1.70 | End |  |

## Related

Installed by:

- [Pop (pop)](https://jbm-ui.bns.studio/catalog/pop.md)
- [Counter (counter)](https://jbm-ui.bns.studio/catalog/counter.md)
- [ProbBar (prob-bar)](https://jbm-ui.bns.studio/catalog/prob-bar.md)
- [Captions (captions)](https://jbm-ui.bns.studio/catalog/captions.md)
- [RebuildScreens (rebuild-screens)](https://jbm-ui.bns.studio/catalog/rebuild-screens.md)
- [Catalog (catalog)](https://jbm-ui.bns.studio/catalog/catalog.md)
- [Propagate (propagate)](https://jbm-ui.bns.studio/catalog/propagate.md)
- [Shelf (shelf)](https://jbm-ui.bns.studio/catalog/shelf.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
