Component library

The MotionActor actor families, distributed as a shadcn registry you install into your own repo.

The runtime gives you actors, signals and deterministic frames. It does not ship a scatter plot. Those live in the component library: a growing set of actor families distributed as a shadcn registry at https://docs.motion.actor/r/motionactor.

It is source distribution, not a dependency. shadcn add copies the actor, its view, its renderer and its demo into your repo, and from that moment you own the code — the same model as shadcn/ui, applied to motion.

Install a component

pnpm dlx shadcn@latest add https://docs.motion.actor/r/motionactor/charts-bar-chart.json

Every item is addressable by name at /r/motionactor/<name>.json, and the index at /r/motionactor/registry.json lists all of them.

What’s in it

102 items today: 64 primitives across sixteen families, and 38 effects.

Family	Items	What it covers
`ui`	18	Interface widgets, text treatments, feedback, utility surfaces
`scene3d`	8	3D scenes, objects, cameras, immersive visual systems
`charts`	6	Animated chart actors and shared charting primitives
`handdrawn`	6	Boiling marker annotations — arrows, rings and titles that redraw every few frames
`media`	6	Images, video, audio, media playback surfaces
`code`	4	Code editors, terminals, file trees, developer UI
`diagrams`	4	Decision flows, network graphs, explanatory diagrams
`input`	2	Input devices, command palettes, keyboard interactions
`layout`	2	Layout and container actors for arranging content
`overlays`	2	Callouts, spotlights, attention-directing overlays
`browser`	1	Browser UI surfaces and panels
`calendar`	1	Calendar layouts and timeline-style date views
`desktop`	1	Desktop windowing and workstation-style surfaces
`documents`	1	Document viewers, annotations, page-based surfaces
`globe`	1	3D globe visualizations and surface renderers
`timelines`	1	Timeline and chronology actors for time-based storytelling

Effects are separate, because they modify an actor rather than being one:

Group	Items	What it covers
`fx-treatments`	17	Persistent looks applied to a subject
`fx-emphasis`	13	Draw the eye to something already on screen
`fx-reveals`	8	Bring a subject on or off screen

See Effects for how an effect attaches to an actor.

The item document

A registry item carries more than files. The extra fields exist so a tool — or an agent — can pick a component without reading its source.

{
  "name": "charts-bar-chart",
  "type": "registry:block",
  "family": "charts",
  "kind": "primitive",
  "entry": "src/components/motionactor/charts/barChart/index.ts",
  "intent": {
    "jobs": ["prove", "compare"],
    "useWhen": "A claim compares a handful of named things and the size of the gap is the argument…",
    "avoidWhen": "Only one figure matters, or there are more categories than a viewer can read…",
    "pairsWith": ["fx-emphasis/bar-shine", "handdrawn/callout-circle"],
    "energy": "measured"
  },
  "controls": { "fields": [ /* … */ ], "commands": [], "targets": [] }
}

PropType

kind?"primitive" | "effect"

Whether the item is an actor you spawn or a treatment you attach to one.

Type"primitive" | "effect"

family?string

The group it belongs to — charts, ui, fx-emphasis, and so on.

Typestring

entry?string

The module to import from once the files land in your repo.

Typestring

intent?object

Editorial selection metadata: which jobs it does (prove, compare, orient, reveal, emphasize, bridge, demonstrate, exhibit, celebrate, agitate, ask), when to reach for it, when not to, what it pairs with, and its energy (calm, measured, energetic, frantic).

Typeobject

controls?object

Every editable signal path on the actor with its kind and default, plus its commands and animation targets. This is what a visual editor binds to.

Typeobject

intent is the field worth knowing about. It is written for the moment before you have picked a component: useWhen and avoidWhen are arguments about when a visual is the right one, not descriptions of what it draws.

Where the source lives

The registry is built from motionactor-library, a separate repository that pins this runtime’s published versions. Engine work happens here; families happen there.

motionactor

packages/* — the @motionactor/* runtime line

motionactor-library

library/* — the actor families

registry/shadcn/motionactor/*.json — the built registry

apps/studio — the browser studio

Because the library pins published runtime versions, a runtime change a family needs ships in two steps: release it here, then bump the pin there.

What to read next

Creating actors

The conventions registry components follow — state layout, commands, render paths.

Effects

How the fx items attach to an actor and compose with each other.

Packages

The runtime line the library pins, and which packages an app installs.