# Concepts URL: https://remocn.dev/docs/ui/concepts The mental model behind remocn-ui primitives — atoms, timeline hooks, theming, and core exports ## Two kinds of atom ### State atoms **State atoms** (Button, Input, Checkbox, Switch) are pure visual functions of `(state | style, theme)`. They read no frame, hold no internal clock, and snap instantly between named states. The component accepts either a `state` (named preset, snap path) or a `style` (resolved, interpolated visual, smooth path) — but never reads the frame itself. The state or style value comes from outside: a direct prop, `useCurrentState`, or a transition hook (see below). **Purity boundary:** `useCurrentFrame()` is never called inside a state atom. Frame resolution happens in the caller — either in `useCurrentState`, `useStateTransition`, or a component's transition hook like `useButtonTransition`. This keeps every state atom safe as a pure renderer. ### Motion atoms **Motion atoms** (Spinner) loop on `useCurrentFrame()` with no discrete states. They are pure functions of the frame and safe in Remotion's headless renderer — no `Date`, no `Math.random`, no `requestAnimationFrame`. Spinner is the first motion atom in this tier. ## Timeline hooks ### `useCurrentState` — snap resolution `useCurrentState` resolves the current state as a **latest-step-wins fold**: it scans the steps array and returns the `state` of the last step whose `at` is at or before the current effective frame. ```ts function useCurrentState( steps: Step[], defaultState: S, speed?: number, ): S ``` - `defaultState` is returned before the first step fires. - `speed` scales the playhead: `effectiveFrame = currentFrame * speed`. A step at `{ at: 30 }` with `speed: 2` activates at render frame 15. - `at` values are always **Sequence-local authored frames** — if the component sits inside ``, Remotion shifts the playhead automatically. ### `useStateTransition` — smooth resolution `useStateTransition` is the lower-level resolver used by transition hooks. It returns the `from` state, the `to` state, and a `progress` value (0 → 1) over the transition window. Transition hooks call this and blend the visuals; you generally do not call it directly. ```ts function useStateTransition( steps: Step[], defaultState: S, speed?: number, defaultDuration?: number, ): { from: S; to: S; progress: number } ``` - `defaultDuration` — frames to animate into a step that omits `duration`. Defaults to `8`. - `progress` ramps from 0 to 1 over `[step.at, step.at + duration)`, then holds at 1. - Ties on `at` resolve later-array-wins (same as `useCurrentState`). ### `Step` ```ts interface Step { /** Sequence-local frame at which this state becomes active. */ at: number; /** The state value to enter at this frame. */ state: S; /** Frames to animate the transition INTO this state. Omitted → caller's defaultDuration. */ duration?: number; } ``` ### `useTypewriter` — typed text reveal `useTypewriter` is the shared typewriter driver. It reads the frame and reveals a string character-by-character at a fixed rate, returning the revealed slice plus status flags. It composes `revealCount` (count math) and `revealedText` (the pure slice), so every surface that types text uses one source of truth. ```ts function useTypewriter( full: string, options?: { cps?: number; speed?: number; startFrame?: number }, ): { text: string; count: number; done: boolean; typing: boolean } ``` - `cps` — characters per second (default `20`). `speed` scales the playhead; `startFrame` delays the start. - `typing` is `true` only while characters are still appearing; pair it with the `caret` primitive so the cursor stays solid mid-type and blinks otherwise: ```tsx const tw = useTypewriter(text, { cps: 22, speed, startFrame: 42 }); {tw.text} ``` Components that already receive a controlled count (`combobox`, `command-menu`) or reveal by state-transition progress (`input`) call `revealedText(full, count)` directly instead of the hook, so they share the same slice without taking on a frame timer. `duration` is consumed by `useStateTransition` (and transition hooks). `useCurrentState` ignores it — snap resolution has no concept of transition length. ## States snap by default State atoms snap instantly between named states — no automatic cross-fade or enter-tween. Snap is the default and cheapest path: author `{ at: N, state: "hover" }` and the atom jumps straight to that visual at frame N. ## Smooth transitions — opt-in via transition hooks Each state atom ships a **transition file** (e.g. `use-button-transition.ts`) that is copied into your project alongside the component. That file: - owns `DEFAULT_DURATION` and easing - exports a `useTransition(steps, opts?) → Style` hook - calls `useStateTransition` internally and interpolates between state presets To get smooth motion, call the hook in your composition and feed the result to the component's `style` prop: ```tsx import { Button } from "@/components/remocn/button"; import { useButtonTransition } from "@/components/remocn/use-button-transition"; export const Scene = () => { const style = useButtonTransition([ { at: 12, state: "hover" }, { at: 30, state: "press" }, { at: 48, state: "loading", duration: 6 }, ]); return