---
title: Component library
description: 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](https://ui.shadcn.com) 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

```bash
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`](https://docs.motion.actor/r/motionactor/registry.json)
lists all of them.

:::info[They are ordinary actors]
  Nothing installed from the registry is privileged. A `BarChart` is a class extending
  `LayoutActor` with signals, commands and a renderer — everything on the
  [Reactivity](/docs/reactivity) and [Runtime](/docs/runtime) pages applies to it
  unchanged, and you can edit it like any other file in your repo.
:::

## 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](/docs/runtime/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.

```json title="/r/motionactor/charts-bar-chart.json"
{
  "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": [] }
}
```

| Prop | Type | Default | Description |
| - | - | - | - |
| `kind?` | `"primitive" \| "effect"` | - | Whether the item is an actor you spawn or a treatment you attach to one. |
| `family?` | `string` | - | The group it belongs to — charts, ui, fx-emphasis, and so on. |
| `entry?` | `string` | - | The module to import from once the files land in your repo. |
| `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). |
| `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. |

`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](/docs/guides/creating-actors)**

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

**[Effects](/docs/runtime/effects)**

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

**[Packages](/docs/packages)**

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