Skip to content

Production-ready animations, transitions, backgrounds, and scenes for Remotion

feat: rewrite

dev_wandry883fedd2d8d5
diff --git a/content/docs/ui/button.mdx b/content/docs/ui/components/button.mdx
similarity index 98%
rename from content/docs/ui/button.mdx
rename to content/docs/ui/components/button.mdx
index 26a1b2d4..cd6e1cf1 100644
--- a/content/docs/ui/button.mdx
+++ b/content/docs/ui/components/button.mdx
@@ -61,7 +61,7 @@ export const Scene = () => {
};
```
-Each `at` is a **Sequence-local authored frame**. State persists between steps: `hover` at frame 8 keeps the button lifted until `press` fires at frame 20. See the [ui tier intro](/docs/ui) for the full `useCurrentState` API.
+Each `at` is a **Sequence-local authored frame**. State persists between steps: `hover` at frame 8 keeps the button lifted until `press` fires at frame 20. See [Concepts](/docs/ui/concepts) for the full `useCurrentState` API.
## Smooth transitions (opt-in)
diff --git a/content/docs/ui/components/meta.json b/content/docs/ui/components/meta.json
new file mode 100644
index 00000000..e1a41f65
--- /dev/null
+++ b/content/docs/ui/components/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Components",
+ "collapsible": false,
+ "pages": ["button", "spinner"]
+}
diff --git a/content/docs/ui/spinner.mdx b/content/docs/ui/components/spinner.mdx
similarity index 100%
rename from content/docs/ui/spinner.mdx
rename to content/docs/ui/components/spinner.mdx
diff --git a/content/docs/ui/concepts.mdx b/content/docs/ui/concepts.mdx
new file mode 100644
index 00000000..6febd735
--- /dev/null
+++ b/content/docs/ui/concepts.mdx
@@ -0,0 +1,161 @@
+---
+title: Concepts
+description: 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<S extends string>(
+ steps: Step<S>[],
+ 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 `<Sequence from={30}>`, 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<S extends string>(
+ steps: Step<S>[],
+ 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<S extends string = string> {
+ /** 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;
+}
+```
+
+`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 `use<Name>Transition(steps, opts?) → <Name>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 <Button label="Continue" style={style} />;
+};
+```
+
+To tune timing globally, edit `DEFAULT_DURATION` in your copied `use-button-transition.ts`. To tune a single transition, add `duration` to that step — it overrides the file default for that transition only. To tune easing, edit the `easings.out(progress)` call in the same file.
+
+## Theming
+
+The `ui` tier uses a JS theme object with stock shadcn token names. Values are concrete oklch strings — not CSS custom properties.
+
+```ts
+import type { RemocnTheme } from "@/lib/remocn-ui";
+
+// All tokens match shadcn's default neutral palette out of the box
+const myTheme: Partial<RemocnTheme> = {
+ primary: "oklch(0.55 0.2 250)", // override just what you need
+ radius: 6,
+};
+```
+
+### `RemocnUIProvider`
+
+Wrap your composition (or a subtree) in `RemocnUIProvider` to set a theme and/or mode for all nested `ui` primitives:
+
+```tsx
+import { RemocnUIProvider } from "@/lib/remocn-ui";
+
+export const Scene = () => (
+ <RemocnUIProvider mode="dark" theme={{ primary: "oklch(0.6 0.22 260)" }}>
+ <Button state={buttonState} label="Continue" />
+ <UICheckbox label="Remember me" state={checkState} />
+ </RemocnUIProvider>
+);
+```
+
+Token resolution order (highest wins): per-component `theme` prop > `RemocnUIProvider` theme > `defaultLightTheme` / `defaultDarkTheme` per `mode`. The `mode` prop on a component wins over `RemocnUIProvider`'s `mode`.
+
+Available exports from `lib/remocn-ui`:
+
+| Export | Type | Description |
+|---|---|---|
+| `RemocnUIProvider` | Component | Context provider for theme and mode |
+| `useRemocnTheme` | Hook | Resolves the active theme inside a component |
+| `defaultLightTheme` | `RemocnTheme` | Stock shadcn neutral light palette |
+| `defaultDarkTheme` | `RemocnTheme` | Stock shadcn neutral dark palette |
+| `RemocnTheme` | Interface | Full token shape with `radius: number` |
+
+### Animated colors require concrete JS values
+
+<Warning>
+CSS custom properties (`var(--primary)`) work for **static** styling only. Remotion's headless per-frame renderer cannot resolve `var(...)` for JS interpolation. If you pass `var(--primary)` as an animated token, `parseColor` will warn in dev mode and fall back to the JS default theme value — not your CSS override.
+
+To override an animated color, pass a concrete oklch, hex, or rgb value via the `theme` prop or `RemocnUIProvider`. Static colors (borders, backgrounds that never animate) can safely use `var()` in `style` props.
+</Warning>
+
+A project whose `:root` overrides `--primary` will see static elements pick up the CSS variable correctly, but state-dependent visuals (hover background, press darkening) will use the JS theme default. The defaults match stock shadcn, so unless you have custom colors, you will not notice the difference — but if you do have custom colors, supply them through the JS theme.
+
+## Core library exports
+
+Installing any component in this tier also installs `lib/remocn-ui/` with these modules:
+
+| Module | Key exports |
+|---|---|
+| `timeline.ts` | `useCurrentState`, `useStateTransition`, `framesFor`, `revealCount` |
+| `theme.ts` | `RemocnUIProvider`, `useRemocnTheme`, `defaultLightTheme`, `defaultDarkTheme` |
+| `color.ts` | `mixOklch`, `parseColor`, `oklchToRgb`, `rgbToOklch`, `toCss` |
+| `motion.ts` | `easings`, `springs` |
+| `types.ts` | `Step` (with optional `duration`) |
+
+You can import from `@/lib/remocn-ui` (the barrel) or from the individual module paths.
diff --git a/content/docs/ui/index.mdx b/content/docs/ui/index.mdx
index bb33da3a..300d91f7 100644
--- a/content/docs/ui/index.mdx
+++ b/content/docs/ui/index.mdx
@@ -1,9 +1,9 @@
---
-title: UI
+title: Introduction
description: shadcn-style primitives scripted on the Remotion timeline
---
-The `ui` tier brings familiar shadcn components — Button, Input, Checkbox, Switch — into Remotion video. Instead of responding to mouse events, their interactions are **scripted on the timeline**: you declare what state a component is in and when, and it renders that state as a deterministic pure function of `useCurrentFrame()`.
+The `ui` tier brings familiar shadcn components — Button, Input, Checkbox, Switch, Spinner — into Remotion video. Instead of responding to mouse events, their interactions are **scripted on the timeline**: you declare what state a component is in and when, and it renders that state as a deterministic pure function of `useCurrentFrame()`.
No `useState`. No event handlers. No CSS transitions. Every pixel is a function of the current frame — which is exactly what Remotion's headless per-frame renderer requires.
@@ -13,207 +13,7 @@ In a browser, a button enters its loading state because the user clicked. In a v
This also means you get things that are impossible in a real UI: scrub backward through a form fill, play a button click at half speed, or loop a checkbox toggle indefinitely — all without any special setup.
-## Installation
+## Where to go next
-Each component installs via the standard shadcn CLI. The shared `remocn-ui` core installs automatically as a `registryDependencies` entry — you do not need to install it separately.
-
-```bash
-npx shadcn add @remocn/button
-```
-
-This writes `components/remocn/button.tsx` and `lib/remocn-ui/` to your project. Every component depends on the same `lib/remocn-ui/` core.
-
-## 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<S extends string>(
- steps: Step<S>[],
- 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 `<Sequence from={30}>`, 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<S extends string>(
- steps: Step<S>[],
- 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<S extends string = string> {
- /** 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;
-}
-```
-
-`duration` is consumed by `useStateTransition` (and transition hooks). `useCurrentState` ignores it — snap resolution has no concept of transition length.
-
-## Usage patterns
-
-### Controlled (canonical)
-
-Pass a state value directly — useful when you want to drive the component from your own logic:
-
-```tsx
-import { Button } from "@/components/remocn/button";
-
-// Always shows the loading state
-export const Scene = () => <Button state="loading" />;
-```
-
-### Timeline-driven
-
-Drive state from the Remotion timeline via `useCurrentState`:
-
-```tsx
-import { useCurrentState } from "@/lib/remocn-ui";
-import { Button } from "@/components/remocn/button";
-
-export const Scene = () => {
- const state = useCurrentState(
- [
- { at: 8, state: "hover" },
- { at: 20, state: "press" },
- { at: 35, state: "loading" },
- { at: 70, state: "success" },
- ],
- "idle",
- );
-
- return <Button state={state} />;
-};
-```
-
-The `at` value is a **Sequence-local authored frame** throughout. State persists between steps: `hover` at frame 8 keeps the button lifted all the way until `press` at frame 20, with no extra bookkeeping.
-
-## 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 `use<Name>Transition(steps, opts?) → <Name>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 <Button label="Continue" style={style} />;
-};
-```
-
-To tune timing globally, edit `DEFAULT_DURATION` in your copied `use-button-transition.ts`. To tune a single transition, add `duration` to that step — it overrides the file default for that transition only. To tune easing, edit the `easings.out(progress)` call in the same file.
-
-## Theming
-
-The `ui` tier uses a JS theme object with stock shadcn token names. Values are concrete oklch strings — not CSS custom properties.
-
-```ts
-import type { RemocnTheme } from "@/lib/remocn-ui";
-
-// All tokens match shadcn's default neutral palette out of the box
-const myTheme: Partial<RemocnTheme> = {
- primary: "oklch(0.55 0.2 250)", // override just what you need
- radius: 6,
-};
-```
-
-### `RemocnUIProvider`
-
-Wrap your composition (or a subtree) in `RemocnUIProvider` to set a theme and/or mode for all nested `ui` primitives:
-
-```tsx
-import { RemocnUIProvider } from "@/lib/remocn-ui";
-
-export const Scene = () => (
- <RemocnUIProvider mode="dark" theme={{ primary: "oklch(0.6 0.22 260)" }}>
- <Button state={buttonState} label="Continue" />
- <UICheckbox label="Remember me" state={checkState} />
- </RemocnUIProvider>
-);
-```
-
-Token resolution order (highest wins): per-component `theme` prop > `RemocnUIProvider` theme > `defaultLightTheme` / `defaultDarkTheme` per `mode`. The `mode` prop on a component wins over `RemocnUIProvider`'s `mode`.
-
-Available exports from `lib/remocn-ui`:
-
-| Export | Type | Description |
-|---|---|---|
-| `RemocnUIProvider` | Component | Context provider for theme and mode |
-| `useRemocnTheme` | Hook | Resolves the active theme inside a component |
-| `defaultLightTheme` | `RemocnTheme` | Stock shadcn neutral light palette |
-| `defaultDarkTheme` | `RemocnTheme` | Stock shadcn neutral dark palette |
-| `RemocnTheme` | Interface | Full token shape with `radius: number` |
-
-### Animated colors require concrete JS values
-
-<Warning>
-CSS custom properties (`var(--primary)`) work for **static** styling only. Remotion's headless per-frame renderer cannot resolve `var(...)` for JS interpolation. If you pass `var(--primary)` as an animated token, `parseColor` will warn in dev mode and fall back to the JS default theme value — not your CSS override.
-
-To override an animated color, pass a concrete oklch, hex, or rgb value via the `theme` prop or `RemocnUIProvider`. Static colors (borders, backgrounds that never animate) can safely use `var()` in `style` props.
-</Warning>
-
-A project whose `:root` overrides `--primary` will see static elements pick up the CSS variable correctly, but state-dependent visuals (hover background, press darkening) will use the JS theme default. The defaults match stock shadcn, so unless you have custom colors, you will not notice the difference — but if you do have custom colors, supply them through the JS theme.
-
-## Core library exports
-
-Installing any component in this tier also installs `lib/remocn-ui/` with these modules:
-
-| Module | Key exports |
-|---|---|
-| `timeline.ts` | `useCurrentState`, `useStateTransition`, `framesFor`, `revealCount` |
-| `theme.ts` | `RemocnUIProvider`, `useRemocnTheme`, `defaultLightTheme`, `defaultDarkTheme` |
-| `color.ts` | `mixOklch`, `parseColor`, `oklchToRgb`, `rgbToOklch`, `toCss` |
-| `motion.ts` | `easings`, `springs` |
-| `types.ts` | `Step` (with optional `duration`) |
-
-You can import from `@/lib/remocn-ui` (the barrel) or from the individual module paths.
+- [Concepts](/docs/ui/concepts) — the mental model: two kinds of atom, timeline hooks, states, theming, and core exports.
+- [Installation](/docs/ui/installation) — add your first component to a Remotion project.
diff --git a/content/docs/ui/installation.mdx b/content/docs/ui/installation.mdx
new file mode 100644
index 00000000..d174d809
--- /dev/null
+++ b/content/docs/ui/installation.mdx
@@ -0,0 +1,35 @@
+---
+title: Installation
+description: Add remocn-ui primitives to an existing Remotion project via the shadcn CLI
+---
+
+## Prerequisites
+
+Remotion must already be set up in your project. remocn-ui does not bootstrap Remotion — it only adds components on top of an existing Remotion setup.
+
+## Install a component
+
+Use the standard shadcn CLI. The shared `remocn-ui` core installs automatically as a `registryDependencies` entry — you do not need to install it separately.
+
+```bash
+npx shadcn add @remocn/button
+```
+
+This writes two things into your project:
+
+- `components/remocn/button.tsx` — the component and its transition hook
+- `lib/remocn-ui/` — the shared core library used by every component in this tier
+
+## Registry dependencies
+
+Some components declare additional `registryDependencies`. For example, a composition that includes a loading indicator will pull in `@remocn/spinner` automatically when you install it. The shadcn CLI resolves and installs the full dependency graph in one command — you only need to name the top-level component you want.
+
+## What gets written
+
+| Path | Contents |
+|---|---|
+| `components/remocn/<name>.tsx` | The state atom component |
+| `components/remocn/use-<name>-transition.ts` | The transition hook for smooth motion (edit `DEFAULT_DURATION` and easing here) |
+| `lib/remocn-ui/` | Shared core — timeline hooks, theme, color utilities, motion helpers, types |
+
+All files are copied into your project. You own the code — edit any file freely to suit your video.
diff --git a/content/docs/ui/meta.json b/content/docs/ui/meta.json
index 158e5caa..08a8b990 100644
--- a/content/docs/ui/meta.json
+++ b/content/docs/ui/meta.json
@@ -1,5 +1,5 @@
{
"title": "UI",
"collapsible": false,
- "pages": ["index", "button", "spinner"]
+ "pages": ["index", "concepts", "installation", "components"]
}
diff --git a/lib/docs-tabs.ts b/lib/docs-tabs.ts
index b8fe0d89..719636e6 100644
--- a/lib/docs-tabs.ts
+++ b/lib/docs-tabs.ts
@@ -51,6 +51,20 @@ function isPrimitivesNode(node: Node): boolean {
);
}
+/**
+ * Hoists a matched folder's own index page and children up to the tab root, so
+ * the Primitives sidebar reads its pages directly (Introduction / Concepts /
+ * Installation / Components) instead of nesting them under a single "UI" group.
+ * Non-folder nodes pass through untouched.
+ */
+function hoistPrimitives(nodes: Node[]): Node[] {
+ return nodes.flatMap((node) =>
+ node.type === "folder"
+ ? [node.index, ...node.children].filter((n): n is Node => Boolean(n))
+ : [node],
+ );
+}
+
/**
* Splits the Fumadocs page tree into the two tab trees. Immutable — the source
* `Root` (shared across requests) is never mutated; each branch is a shallow
@@ -64,6 +78,9 @@ function isPrimitivesNode(node: Node): boolean {
* would never change when `DocsShell` swaps trees on a tab switch, freezing the
* sidebar on the first tab until a full page reload. Distinct ids make the dep
* differ per tab so the sidebar updates client-side.
+ *
+ * The Primitives branch is additionally hoisted (see {@link hoistPrimitives}) so
+ * the remocn-ui pages render at the sidebar root without a wrapping "UI" label.
*/
export function splitDocsTree(tree: Root): {
components: Root;
@@ -78,7 +95,7 @@ export function splitDocsTree(tree: Root): {
primitives: {
...tree,
$id: "docs-tab-primitives",
- children: tree.children.filter(isPrimitivesNode),
+ children: hoistPrimitives(tree.children.filter(isPrimitivesNode)),
},
};
}