Custom previews

Save a component with your own args in a registry, from the editor, an MCP client, or the AI assistant.

New in 2.1.0. A custom preview is a component rendered with args that a signed-in reader saves in the registry. Every reader sees it in the preview picker next to the built previews. The registry does not build anything for it.

Custom previews exist only in registry mode.

Create one in the editor

Open a component page in the registry and select a built preview.
Click Create. The editor opens with the args of that preview.
Change the args in the Form view (one control per property, including object, array, and union properties) or the JSON view. The live preview updates, and the editor checks the args against the component properties as you type.
Give the preview a title and save it.

Create stays disabled for a component published before 2.1.0, because it has no render shell. Republish the component to enable it.

Who can change what

Any signed-in member can create a custom preview.
Only its author or an administrator can change or delete it.
An access token needs previews:write or registry:write to save previews. Any member can create a previews:write token, which cannot publish. See Accounts and access.

When a component changes

A custom preview stores the component id and the complete args, with no link to a built preview. A republished component does not break it.

Each read checks the saved args against the current properties and reports unknown properties, missing required properties, and type mismatches.
At render time, a missing required property gets its default value.

From coding agents and the assistant

In a registry, the MCP endpoint adds five tools:

Tool	Does
`handoff_list_custom_previews`	Lists the saved custom previews of a component
`handoff_get_custom_preview`	Reads one, with its args and any issues
`handoff_create_custom_preview`	Saves a new one
`handoff_update_custom_preview`	Changes the title, description, or args
`handoff_delete_custom_preview`	Deletes one for every reader

handoff_get_component also returns argsSchema, the JSON Schema to write args against, and customPreviews, the ones already saved.

The AI assistant can create and change custom previews for the signed-in reader, for example "a disabled version with a long label". Inside the editor, it changes the open preview, and the editor offers to load the change.

Isolation

Any member can save args, and a component can run script from them. So the registry renders custom previews from a render shell that the build emits (component/<id>.render.html), at an opaque origin: the frame has sandbox="allow-scripts", and both routes that serve the shell send Content-Security-Policy: sandbox allow-scripts.

Upgrade to 2.1.0

Run db:migrate. It adds the component_custom_previews table.
Rebuild the registry.
Republish your components so each one has a render shell.