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: work with an agent that has the vizchat-widget skill (it ships with the VizChat plugin and is also checked into the repository for contributors). It walks through requirements → scaffold → implement → verify — the same steps as the manual flow, with fewer mistakes.

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 data contract in src/definition.ts (snapshot schema, default snapshot, operations) and the view — a React component for inline, mount / render callbacks for nested. 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 publish with ./scripts/release.sh content, which pushes the source, compiles it and publishes a new version, returning once publishing has finished. Widget source changes are not hot-reloaded; run the script and refresh the page to see them.

A widget's package.json declares only its identity — mount, display name and default size. Where the source lives is a fixed convention (src/definition.ts, src/index.tsx or src/index.ts, src/i18n/), the same for every widget, so there is nothing else to configure.

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 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