Build a custom widget

When the built-in widgets don't cover what you need, there are three paths. Almost everyone wants the first one.

Path 1: ask the agent (no code, no repo)

Describe the widget you want in the chat — a countdown timer, a kanban board, a calculator, a bespoke interactive component. The agent scaffolds it, writes the code, compiles and checks it, and publishes it to your private library.

The result behaves exactly like a built-in widget: it has its own data and configuration, the agent can drive it, and you can reuse it across documents. You can also publish it to the Marketplace so other people can use and favorite it.

This is the path the product is designed around, and it needs nothing installed.

Path 2: author a built-in widget (repo contributors)

Built-in widgets live in the VizChat repository and ship with the product. This path is for contributing a widget back to VizChat itself, not for one-off needs.

Prerequisites: the repo cloned with a working local dev environment, and comfort with TypeScript and Zod.

Recommended: use the /build-builtin-widget skill, which walks through requirements → scaffold → implement → verify. It performs the same steps as the manual flow and is less error-prone.

The manual flow is:

1. Scaffold with the create:widget script, choosing how the widget mounts — inline (rendered in the host page) or nested (rendered in its own frame).
2. Implement the schema, the reducers, and the view. Use an existing widget in builtin-widgets/ as the reference — bar-chart is a good starting point.
3. Verify with type-checking and the widget's unit tests.
4. Compile and seed by restarting the backend, which compiles built-in widgets and seeds them to object storage. Widget source changes are not hot-reloaded, so restart and refresh to see them.

Each widget declares its own metadata and entry point in its package.json; the exact fields are defined by the scaffold template rather than listed here, so they stay correct as the toolchain evolves.

Path 3: develop locally and publish with the CLI (independent developers)

Develop a widget on your own machine with your own editor, then use the vizchat-widget CLI to log in, preview it locally (with narrated demos), and publish it to the Marketplace — no VizChat repo clone required. See Publish a widget from the command line for the full walkthrough.

Which path do I want?

Next step

• Widget types overview
• What a widget is