Reelify Motion Kit 0.1 preview
Docs/Guide

Custom components

The four levels of making a component your own, from setting props to a build function, where a component can live, and how to check it.

There are four levels of customisation. Each costs more than the one before it. Use the lowest level that does the job.

LevelWhat you writeWhere
1. AdjustProps, parts, or a surface.On one instance, or in a design system.
2. Preset{ "name", "extends", "defaults" }A components list.
3. Component as data{ "name", "props", "tree" }A components list.
4. Build functionbuild(props, env) returning a tree.The registry, in code.

81 of the 89 shipped components are level 3. The other 8 are level 4.

Level 1: adjust#

Set props#

Every component exposes what is worth changing: words, numbers, colours and two or three motion values such as bounce or each. Each component page lists them with ranges and defaults.

These props are accepted by every component and go to its root node: place, w, h, grow, rotate, scale, opacity, origin, start, glow, backface, aperture. A component's own prop of the same name takes precedence. Any node's own motion works on a component too.

Restyle a part#

parts changes one named node inside one instance. A part takes the props of the element it is, plus motion, which is added to the part's own.

json
{ "el": "StatReveal", "value": 82, "suffix": "%",
  "parts": { "value": { "color": "bad" }, "bar": { "fill": "bad" } } }

Change a surface#

Components that draw a card, a chip or a panel sit on a named surface. Redefining that surface in the scene's or the design system's surfaces restyles every component that uses it. See Design systems. To change one component's defaults everywhere, use the system's defaults.

Level 2: a preset#

A preset is an existing component under a new name with new defaults, restyled parts and extra motion.

json
{ "name": "BrandStat", "extends": "StatReveal",
  "defaults": { "color": "accent2", "bounce": 0.6, "size": 150 },
  "parts": { "label": { "upper": true } } }
KeyMeaning
nameThe new component's name.
extendsThe component it restyles. It must exist.
defaultsNew default props. A required prop that gets a default stops being required.
partsPart restyles applied to every use.
motionBehaviors added to every use.
descriptionOptional. Shown in the catalog.

A preset has the same props, parts and slots as its base. An instance can still set any prop and restyle any part.

The same component three ways: props only, two parts restyled on one instance, and a preset defined in the scene.

Level 3: a component as data#

json
{ "name": "PriceTag",
  "description": "A price on a tag that swings in.",
  "props": { "price": { "type": "string", "req": true }, "ink": { "type": "color", "default": "ink" } },
  "tree": { "el": "box", "surface": "card",
    "motion": [{ "do": "enter", "from": { "rotate": -12, "y": -80, "opacity": 0 }, "curve": "bouncy" }],
    "children": [{ "el": "text", "id": "price", "text": "$price", "size": 96, "weight": 800, "color": "$ink" }] },
  "example": { "el": "PriceTag", "price": "$9" } }

Props#

Each prop is a field declaration. One declaration gives the check, the default, the line in the generated reference and the control in an editor.

TypeExtra keys
numbermin, max, integer
string, bool, color
enumvalues
timeSeconds or a cue name.
curve, pose, pointA curve or pose by name or as an object. A point is [x, y].
listof: the field each item is.
objectfields: a field per key.

Every field also takes default, req (required) and desc. Give every prop a default unless it is required. A list of records is declared like this:

json
{ "type": "list", "of": { "type": "object", "fields": {
  "text": { "type": "string" }, "ok": { "type": "bool" } } } }

The tree#

The tree is a node made of elements and other components. Inside it, at any depth:

  • "$price" is the prop's value. "$item.text" reaches into a record.
  • "=expr" is arithmetic with numeric props by name: "w": "=size*2.1".
  • "{price}" inside a longer text is filled in.
  • $each repeats a node over a list prop or a count. $if picks a value from a bool prop.

See Expressions for all of these.

Ids are parts#

Give an id to each node someone may want to restyle. Those ids are the component's parts, and root is always one. Leave fill and radius to a surface and use palette names, so the component follows any design system.

Slots and $children#

"$children" in a children list is where the nodes wrapped by the component go. Wrappers such as Phone, Window and Float3D are built this way.

A named slot is a declared insertion point. Declare it under slots, place it with { "$slot": "name" }, and fill it on an instance with "slots": { "name": [nodes] }.

  • A slot's declaration is a description, or a contract: { "description": "…", "elements": ["icon", "text"], "max": 1 }. Breaking the contract is a problem.
  • { "$slot": "name", "fallback": [NODE] } gives the content used when the instance supplies none. An instance passes [] to clear a slot.
  • Nodes supplied to a slot are written in the caller's scope. They read the scene's tokens, not the component's props.
A component defined in the scene: three props, a slot with a contract, two parts, and a list rendered with $each. The second use fills the slot, restyles a part and starts 0.3 seconds later.

State#

A component can declare signals. Every use gets its own copy, and the clock starts when that instance does. The parts read it in "=expr" and "{expr}", so one value moves several parts together.

One piece of state, on, moves the knob, blends the track's colour and raises the label's opacity. Each of the three uses has its own on.

A state name cannot match one of the component's props or a built-in name (t, lt, dur, selfW, selfH, parentW, parentH). Each piece of state can read the ones declared before it.

Level 4: a build function#

A few things cannot be written as a tree: turning a transcript into caption lines, laying scenes end to end, computing a node count from data. For those a component has build: a function from its props to a tree. What it returns is ordinary nodes, checked like any others.

ts
import { defineComponent, starter } from "./motion-kit/src/index";

const registry = starter();

defineComponent(registry, {
  name: "Countdown",
  description: "Numbers that count down, one per second.",
  category: "Type",
  props: { from: { type: "number", default: 3, min: 1, max: 10, integer: true } },
  tree: { el: "box" },
  build: (p) => ({
    el: "box", dir: "stack", local: true,
    children: Array.from({ length: p.from }, (_, i) => ({
      el: "text", text: String(p.from - i), size: 300,
      motion: [{ do: "during", at: i, until: i + 1 }, { do: "enter", from: "pop", at: i }],
    })),
  }),
  example: { el: "Countdown", from: 3 },
});
  • build(props, env) receives the props with defaults filled in. env holds the scene's transcript, cues, duration and size, and problem(message) to report one.
  • tree is still required. It is the fallback shape and can be a bare box.
  • local: true on the returned root makes the numbers inside count from the instance's start.
  • A build function is code, so it cannot live in a scene or a config. It lives in the registry.
A component with build is not data. It does not survive a JSON round trip, an agent cannot define one in a film, and a host must ship it. Use level 3 unless the node structure itself must be computed.

Where a component can live#

PlaceHowScope
A sceneThe scene's components list.That scene. It travels with the JSON.
A configThe config's components list.Every scene the config is put under. A brand's own pieces travel with its colours.
The librarydefineComponent(registry, def).Every scene compiled with that registry. Required for build.

When a scene and a config define the same name, withConfig keeps one by name: the scene's, or the config's with force. A component cannot take the name of an element or Motion.

Checking it#

  • Run npx tsx cli.ts check scene.json on a scene that uses the component. Definitions are checked when used, so include at least one instance.
  • A mistake inside the tree is reported with the component's name and the path to the node. An unknown "$name" lists the props that exist.
  • Passing a prop the component does not declare is a problem. So is a missing required prop, a value out of range, an undeclared slot, and a part name that does not exist.
  • npx tsx cli.ts snapshot scene.json lists each instance with its values, parts and slots. For a library component, catalog Name prints its props, tree and parts.
  • Give the definition an example. The generated reference prints it, and it is the first thing an agent copies.
Reelify Motion Kit 0.1 preview. Built 2026-11-21.llms.txt · SKILL.md · 109 pages