Skip to content

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

feat: setup icons docs shell

dev_wandrye62ca732360d
diff --git a/app/docs/layout.tsx b/app/docs/layout.tsx
index 1f130df1..35221ff2 100644
--- a/app/docs/layout.tsx
+++ b/app/docs/layout.tsx
@@ -11,7 +11,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
// `withNewBadges`), then split it into the Components / Primitives tab trees
// (see `splitDocsTree`). Both run on the server; `DocsShell` picks the tree
// matching the active tab by pathname so each tab owns its own sidebar.
- const { components, primitives, shaders } = splitDocsTree(
+ const { components, primitives, shaders, icons } = splitDocsTree(
withNewBadges(source.pageTree),
);
@@ -27,6 +27,7 @@ export default async function Layout({ children }: { children: ReactNode }) {
componentsTree={components}
primitivesTree={primitives}
shadersTree={shaders}
+ iconsTree={icons}
>
{children}
</DocsShell>
diff --git a/components/docs/docs-shell.tsx b/components/docs/docs-shell.tsx
index 38bb4f56..b31d9f8d 100644
--- a/components/docs/docs-shell.tsx
+++ b/components/docs/docs-shell.tsx
@@ -35,11 +35,13 @@ export function DocsShell({
componentsTree,
primitivesTree,
shadersTree,
+ iconsTree,
children,
}: {
componentsTree: Root;
primitivesTree: Root;
shadersTree: Root;
+ iconsTree: Root;
children: ReactNode;
}) {
const pathname = usePathname();
@@ -49,7 +51,9 @@ export function DocsShell({
? primitivesTree
: activeTab === "shaders"
? shadersTree
- : componentsTree;
+ : activeTab === "icons"
+ ? iconsTree
+ : componentsTree;
return (
<DocsLayout
diff --git a/components/docs/icons-gallery.tsx b/components/docs/icons-gallery.tsx
new file mode 100644
index 00000000..e3db619b
--- /dev/null
+++ b/components/docs/icons-gallery.tsx
@@ -0,0 +1,204 @@
+"use client";
+
+import { Player, type PlayerRef } from "@remotion/player";
+import { Check, Copy, Search } from "lucide-react";
+import type { ComponentType } from "react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { usePrefersReducedMotion } from "@/lib/use-prefers-reduced-motion";
+import { cn } from "@/lib/utils";
+import registry, { type RegistryEntry } from "@/registry/__index__";
+
+export type IconCategory =
+ | "Status & feedback"
+ | "Actions & UI"
+ | "Emotion & accents"
+ | "Arrows & navigation";
+
+export interface IconEntry {
+ name: string;
+ label: string;
+ category: IconCategory;
+ Static: ComponentType<{
+ size?: number;
+ strokeWidth?: number;
+ className?: string;
+ }>;
+}
+
+export const ICONS: IconEntry[] = [];
+
+const CATEGORY_ORDER: IconCategory[] = [
+ "Status & feedback",
+ "Actions & UI",
+ "Emotion & accents",
+ "Arrows & navigation",
+];
+
+const TILE_SIZE = 56;
+
+export function IconsGallery() {
+ const [query, setQuery] = useState("");
+ const [active, setActive] = useState<string | null>(null);
+
+ const filtered = useMemo(() => {
+ const q = query.trim().toLowerCase();
+ if (!q) return ICONS;
+ return ICONS.filter(
+ (icon) =>
+ icon.label.toLowerCase().includes(q) ||
+ icon.name.toLowerCase().includes(q),
+ );
+ }, [query]);
+
+ const groups = useMemo(
+ () =>
+ CATEGORY_ORDER.map((category) => ({
+ category,
+ icons: filtered.filter((icon) => icon.category === category),
+ })).filter((group) => group.icons.length > 0),
+ [filtered],
+ );
+
+ return (
+ <div className="not-prose flex flex-col gap-8">
+ <div className="relative max-w-xs">
+ <Search className="pointer-events-none absolute top-1/2 left-3 size-4 -translate-y-1/2 text-muted-foreground" />
+ <input
+ type="search"
+ value={query}
+ onChange={(event) => setQuery(event.target.value)}
+ placeholder="Filter icons…"
+ className="w-full rounded-lg border border-fd-border bg-fd-background py-2 pr-3 pl-9 text-sm text-foreground outline-none focus-visible:ring-2 focus-visible:ring-ring/40"
+ />
+ </div>
+
+ {groups.length === 0 ? (
+ <p className="text-sm text-muted-foreground">
+ {ICONS.length === 0
+ ? "Icons are coming soon."
+ : "No icons match your filter."}
+ </p>
+ ) : (
+ groups.map((group) => (
+ <section key={group.category} className="flex flex-col gap-3">
+ <h3 className="text-sm font-medium text-muted-foreground">
+ {group.category}
+ </h3>
+ <div className="grid grid-cols-[repeat(auto-fill,minmax(112px,1fr))] gap-3">
+ {group.icons.map((icon) => (
+ <IconTile
+ key={icon.name}
+ icon={icon}
+ active={active === icon.name}
+ onActivate={() => setActive(icon.name)}
+ onDeactivate={() =>
+ setActive((current) =>
+ current === icon.name ? null : current,
+ )
+ }
+ />
+ ))}
+ </div>
+ </section>
+ ))
+ )}
+ </div>
+ );
+}
+
+function IconTile({
+ icon,
+ active,
+ onActivate,
+ onDeactivate,
+}: {
+ icon: IconEntry;
+ active: boolean;
+ onActivate: () => void;
+ onDeactivate: () => void;
+}) {
+ const reducedMotion = usePrefersReducedMotion();
+ const [copied, setCopied] = useState(false);
+ const entry = registry[`icon-${icon.name}`];
+ const command = `npx shadcn@latest add @remocn/icon-${icon.name}`;
+ const playing = active && !reducedMotion && Boolean(entry);
+ const Static = icon.Static;
+
+ const handleCopy = () => {
+ navigator.clipboard.writeText(command);
+ setCopied(true);
+ setTimeout(() => setCopied(false), 1500);
+ };
+
+ return (
+ <button
+ type="button"
+ onClick={handleCopy}
+ onMouseEnter={onActivate}
+ onMouseLeave={onDeactivate}
+ onFocus={onActivate}
+ onBlur={onDeactivate}
+ title={command}
+ aria-label={`Copy install command for ${icon.label}`}
+ className={cn(
+ "surface-card group relative flex aspect-square flex-col items-center justify-center gap-2 rounded-xl p-3 text-muted-foreground transition-colors",
+ "hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40",
+ )}
+ >
+ <span
+ className="flex items-center justify-center"
+ style={{ width: TILE_SIZE, height: TILE_SIZE }}
+ >
+ {playing && entry ? (
+ <IconPlayer entry={entry} />
+ ) : (
+ <Static size={TILE_SIZE} strokeWidth={2} />
+ )}
+ </span>
+ <span className="max-w-full truncate text-xs">{icon.label}</span>
+ <span className="absolute top-1.5 right-1.5 opacity-0 transition-opacity group-hover:opacity-100 group-focus-visible:opacity-100">
+ {copied ? (
+ <Check className="size-3.5" />
+ ) : (
+ <Copy className="size-3.5" />
+ )}
+ </span>
+ </button>
+ );
+}
+
+function IconPlayer({ entry }: { entry: RegistryEntry }) {
+ const playerRef = useRef<PlayerRef>(null);
+ const { config, load } = entry;
+
+ useEffect(() => {
+ let raf1 = 0;
+ let raf2 = 0;
+ raf1 = requestAnimationFrame(() => {
+ playerRef.current?.play();
+ raf2 = requestAnimationFrame(() => {
+ if (playerRef.current && !playerRef.current.isPlaying()) {
+ playerRef.current.play();
+ }
+ });
+ });
+ return () => {
+ if (raf1) cancelAnimationFrame(raf1);
+ if (raf2) cancelAnimationFrame(raf2);
+ };
+ }, []);
+
+ return (
+ <Player
+ ref={playerRef}
+ lazyComponent={load}
+ durationInFrames={config.durationInFrames}
+ fps={config.fps}
+ compositionWidth={config.compositionWidth}
+ compositionHeight={config.compositionHeight}
+ style={{ width: TILE_SIZE, height: TILE_SIZE }}
+ loop
+ acknowledgeRemotionLicense
+ />
+ );
+}
diff --git a/config/site.ts b/config/site.ts
index d1d40935..9fd666e5 100644
--- a/config/site.ts
+++ b/config/site.ts
@@ -43,6 +43,7 @@ export type NavLink = {
export const NAV_LINKS: NavLink[] = [
{ href: "/docs/typography", label: "Components" },
{ href: "/docs/shaders/getting-started/introduction", label: "Shaders" },
+ { href: "/docs/icons/getting-started/introduction", label: "Icons" },
{ href: "/sponsors", label: "Sponsors" },
{ href: "/docs/getting-started/introduction", label: "Docs" },
];
@@ -57,6 +58,7 @@ export const NEW_BADGE_PATHS = new Set<string>([
"/docs/layout/drift",
"/docs/typography/rolodex-flip",
"/docs/typography/value-swap",
+ "/docs/icons/gallery",
]);
export const FOOTER_NAV: NavLink[] = [
diff --git a/content/docs/icons/gallery.mdx b/content/docs/icons/gallery.mdx
new file mode 100644
index 00000000..30992142
--- /dev/null
+++ b/content/docs/icons/gallery.mdx
@@ -0,0 +1,8 @@
+---
+title: Gallery
+description: Browse every remocn icon, hover to play its motion, and copy the install command
+---
+
+Hover or focus a tile to play its animation, then click to copy the install command.
+
+<IconsGallery />
diff --git a/content/docs/icons/getting-started/introduction.mdx b/content/docs/icons/getting-started/introduction.mdx
new file mode 100644
index 00000000..5c6510db
--- /dev/null
+++ b/content/docs/icons/getting-started/introduction.mdx
@@ -0,0 +1,67 @@
+---
+title: Introduction
+description: Line-drawn Lucide icons re-authored for Remotion with a two-phase draw and action motion system
+---
+
+remocn icons are animated line icons built for video. Each one is a [Lucide](https://lucide.dev) glyph re-authored on the Remotion API, so it draws itself on and then performs a small action — a checkmark strikes, a bell rings, a heart beats — as a pure function of the timeline. Same input frame, same pixels, every render.
+
+Every icon shares one animation contract and one motion system, so switching icons never changes the surrounding scene. Install a single icon with:
+
+```bash
+npx shadcn@latest add @remocn/icon-check
+```
+
+## The two-phase motion system
+
+An icon runs in two phases:
+
+- **Draw** — the strokes trace themselves on, staggered by path, then a spring settles the whole glyph into place.
+- **Action** — a short, icon-specific gesture that reads the meaning at a glance. The action can play once or loop.
+
+The `animation` prop selects which phases run: `draw` stops after the strokes are on, `action` skips the draw and starts mid-gesture, and `both` (the default) draws and then acts.
+
+Compose an icon like any other remocn primitive — offset it in time with `<Sequence>` and place it next to a text animation:
+
+```tsx
+import { AbsoluteFill, Sequence } from "remotion";
+import { CheckIcon } from "@/components/remocn/icon-check";
+import { SoftBlurIn } from "@/components/remocn/soft-blur-in";
+
+export const Scene = () => (
+ <AbsoluteFill className="items-center justify-center gap-6">
+ <Sequence from={0}>
+ <CheckIcon size={64} color="#22c55e" />
+ </Sequence>
+ <Sequence from={12}>
+ <SoftBlurIn text="Done" />
+ </Sequence>
+ </AbsoluteFill>
+);
+```
+
+## Shared props
+
+Every icon accepts the same `IconAnimationProps`. This is the single reference — individual icons only add their own defaults, never new controls.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `animation` | `draw` / `action` / `both` | `both` | Which phases run. |
+| `loop` | `boolean` | `false` | Repeat the action phase forever. |
+| `speed` | `number` | `1` | Timeline multiplier applied before the animation math. |
+| `size` | `number` | `48` | Icon width and height in pixels. |
+| `color` | `string` | `currentColor` | Stroke color. |
+| `strokeWidth` | `number` | `2` | Stroke width in SVG units. |
+| `className` | `string` | — | Passed to the root SVG. |
+
+## Loops by default
+
+A few icons express motion that never resolves, so they loop out of the box. Pass `loop={false}` to play them once:
+
+- `loader`
+- `refresh-cw`
+- `sparkles`
+- `flame`
+
+## Attribution
+
+Icon paths are derived from [Lucide](https://lucide.dev), licensed under the [ISC License](https://github.com/lucide-icons/lucide/blob/main/LICENSE). The motion is inspired by [lucide-animated](https://github.com/lucide-icons/lucide), re-authored from scratch for deterministic Remotion video.
diff --git a/content/docs/icons/getting-started/meta.json b/content/docs/icons/getting-started/meta.json
new file mode 100644
index 00000000..89d653a4
--- /dev/null
+++ b/content/docs/icons/getting-started/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Getting Started",
+ "collapsible": false,
+ "pages": ["introduction"]
+}
diff --git a/content/docs/icons/meta.json b/content/docs/icons/meta.json
new file mode 100644
index 00000000..1e7eb571
--- /dev/null
+++ b/content/docs/icons/meta.json
@@ -0,0 +1,5 @@
+{
+ "title": "Icons",
+ "collapsible": false,
+ "pages": ["getting-started", "gallery"]
+}
diff --git a/content/docs/meta.json b/content/docs/meta.json
index ae3ac085..3b212dd5 100644
--- a/content/docs/meta.json
+++ b/content/docs/meta.json
@@ -7,6 +7,7 @@
"ui",
"environment",
"shaders",
+ "icons",
"ui-blocks",
"ai",
"transitions",
diff --git a/lib/docs-tabs.test.ts b/lib/docs-tabs.test.ts
new file mode 100644
index 00000000..a5613d01
--- /dev/null
+++ b/lib/docs-tabs.test.ts
@@ -0,0 +1,139 @@
+import { describe, expect, it } from "bun:test";
+import type { Node, Root } from "fumadocs-core/page-tree";
+
+import { getActiveDocsTab, splitDocsTree } from "./docs-tabs";
+
+const tree: Root = {
+ $id: "root",
+ name: "Docs",
+ children: [
+ { type: "page", name: "Typography", url: "/docs/typography" },
+ {
+ type: "folder",
+ name: "UI",
+ index: { type: "page", name: "UI", url: "/docs/ui" },
+ children: [{ type: "page", name: "Concepts", url: "/docs/ui/concepts" }],
+ },
+ {
+ type: "folder",
+ name: "Shaders",
+ children: [
+ {
+ type: "folder",
+ name: "Getting Started",
+ children: [
+ {
+ type: "page",
+ name: "Introduction",
+ url: "/docs/shaders/getting-started/introduction",
+ },
+ ],
+ },
+ ],
+ },
+ {
+ type: "folder",
+ name: "Icons",
+ children: [
+ {
+ type: "folder",
+ name: "Getting Started",
+ children: [
+ {
+ type: "page",
+ name: "Introduction",
+ url: "/docs/icons/getting-started/introduction",
+ },
+ ],
+ },
+ { type: "page", name: "Gallery", url: "/docs/icons/gallery" },
+ ],
+ },
+ ],
+};
+
+function collectUrls(nodes: Node[]): string[] {
+ const urls: string[] = [];
+ for (const node of nodes) {
+ if (node.type === "page") urls.push(node.url);
+ else if (node.type === "folder") {
+ if (node.index) urls.push(node.index.url);
+ urls.push(...collectUrls(node.children));
+ }
+ }
+ return urls;
+}
+
+describe("splitDocsTree", () => {
+ it("routes icons pages only into the icons branch", () => {
+ const { icons } = splitDocsTree(tree);
+ const urls = collectUrls(icons.children);
+ expect(urls).toContain("/docs/icons/getting-started/introduction");
+ expect(urls).toContain("/docs/icons/gallery");
+ expect(urls.every((url) => url.startsWith("/docs/icons"))).toBe(true);
+ });
+
+ it("excludes icons, shaders, and primitives from the components branch", () => {
+ const { components } = splitDocsTree(tree);
+ const urls = collectUrls(components.children);
+ expect(urls).toContain("/docs/typography");
+ expect(urls.some((url) => url.startsWith("/docs/icons"))).toBe(false);
+ expect(urls.some((url) => url.startsWith("/docs/shaders"))).toBe(false);
+ expect(urls.some((url) => url.startsWith("/docs/ui"))).toBe(false);
+ });
+
+ it("keeps shaders and icons in separate branches", () => {
+ const { shaders, icons } = splitDocsTree(tree);
+ expect(
+ collectUrls(shaders.children).some((url) =>
+ url.startsWith("/docs/icons"),
+ ),
+ ).toBe(false);
+ expect(
+ collectUrls(icons.children).some((url) =>
+ url.startsWith("/docs/shaders"),
+ ),
+ ).toBe(false);
+ });
+
+ it("gives every branch a distinct, stable $id", () => {
+ const { components, primitives, shaders, icons } = splitDocsTree(tree);
+ expect(components.$id).toBe("docs-tab-components");
+ expect(primitives.$id).toBe("docs-tab-primitives");
+ expect(shaders.$id).toBe("docs-tab-shaders");
+ expect(icons.$id).toBe("docs-tab-icons");
+ expect(
+ new Set([
+ components.$id,
+ primitives.$id,
+ shaders.$id,
+ icons.$id,
+ ]).size,
+ ).toBe(4);
+ });
+
+ it("does not mutate the source tree", () => {
+ const before = tree.children.length;
+ splitDocsTree(tree);
+ expect(tree.children.length).toBe(before);
+ expect(tree.$id).toBe("root");
+ });
+});
+
+describe("getActiveDocsTab", () => {
+ it("selects the icons tab for icons paths", () => {
+ expect(getActiveDocsTab("/docs/icons")).toBe("icons");
+ expect(getActiveDocsTab("/docs/icons/gallery")).toBe("icons");
+ expect(
+ getActiveDocsTab("/docs/icons/getting-started/introduction"),
+ ).toBe("icons");
+ });
+
+ it("does not misroute other tabs", () => {
+ expect(getActiveDocsTab("/docs/typography")).toBe("components");
+ expect(getActiveDocsTab("/docs/ui")).toBe("primitives");
+ expect(
+ getActiveDocsTab("/docs/shaders/getting-started/introduction"),
+ ).toBe("shaders");
+ });
+});
diff --git a/lib/docs-tabs.ts b/lib/docs-tabs.ts
index 85151787..7c60a850 100644
--- a/lib/docs-tabs.ts
+++ b/lib/docs-tabs.ts
@@ -7,7 +7,7 @@ import type { Node, Root } from "fumadocs-core/page-tree";
* unchanged from the flat docs structure. No files move and no URLs change —
* the split is purely a view over the existing Fumadocs page tree.
*/
-export type DocsTabId = "components" | "primitives" | "shaders";
+export type DocsTabId = "components" | "primitives" | "shaders" | "icons";
export type DocsTab = {
id: DocsTabId;
@@ -28,6 +28,11 @@ export const DOCS_TABS: DocsTab[] = [
label: "Shaders",
href: "/docs/shaders/getting-started/introduction",
},
+ {
+ id: "icons",
+ label: "Icons",
+ href: "/docs/icons/getting-started/introduction",
+ },
];
/** URL prefix that backs the Primitives tab (the remocn-ui section). */
@@ -49,8 +54,15 @@ function isShadersPath(pathname: string): boolean {
);
}
+const ICONS_PREFIX = "/docs/icons";
+
+function isIconsPath(pathname: string): boolean {
+ return pathname === ICONS_PREFIX || pathname.startsWith(`${ICONS_PREFIX}/`);
+}
+
export function getActiveDocsTab(pathname: string): DocsTabId {
if (isShadersPath(pathname)) return "shaders";
+ if (isIconsPath(pathname)) return "icons";
if (isPrimitivesPath(pathname)) return "primitives";
return "components";
}
@@ -81,6 +93,21 @@ function isShadersNode(node: Node): boolean {
return node.children.some(hasShadersDescendant);
}
+function hasIconsDescendant(node: Node): boolean {
+ if (node.type === "page") return node.url.startsWith(`${ICONS_PREFIX}/`);
+ if (node.type === "folder") {
+ if (node.index?.url === ICONS_PREFIX) return true;
+ return node.children.some(hasIconsDescendant);
+ }
+ return false;
+}
+
+function isIconsNode(node: Node): boolean {
+ if (node.type !== "folder") return false;
+ if (node.index?.url === ICONS_PREFIX) return true;
+ return node.children.some(hasIconsDescendant);
+}
+
/**
* 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 /
@@ -116,13 +143,17 @@ export function splitDocsTree(tree: Root): {
components: Root;
primitives: Root;
shaders: Root;
+ icons: Root;
} {
return {
components: {
...tree,
$id: "docs-tab-components",
children: tree.children.filter(
- (node) => !isPrimitivesNode(node) && !isShadersNode(node),
+ (node) =>
+ !isPrimitivesNode(node) &&
+ !isShadersNode(node) &&
+ !isIconsNode(node),
),
},
primitives: {
@@ -135,5 +166,10 @@ export function splitDocsTree(tree: Root): {
$id: "docs-tab-shaders",
children: hoistPrimitives(tree.children.filter(isShadersNode)),
},
+ icons: {
+ ...tree,
+ $id: "docs-tab-icons",
+ children: hoistPrimitives(tree.children.filter(isIconsNode)),
+ },
};
}
diff --git a/mdx-components.tsx b/mdx-components.tsx
index fd42fc13..8db602e5 100644
--- a/mdx-components.tsx
+++ b/mdx-components.tsx
@@ -6,6 +6,7 @@ import { ComponentCardGrid } from "@/components/docs/component-card-grid";
import { ComponentExample } from "@/components/docs/component-example";
import { ComponentPreview } from "@/components/docs/component-preview";
import { Dependencies } from "@/components/docs/dependencies";
+import { IconsGallery } from "@/components/docs/icons-gallery";
import { InstallAll } from "@/components/docs/install-all";
import { InstallBlock } from "@/components/docs/install-block";
import { PropsTable } from "@/components/docs/props-table";
@@ -46,6 +47,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
Warning,
Dependencies,
ComponentCardGrid,
+ IconsGallery,
...components,
};