User Widgets
Component instances generated by the Agent at runtime, discoverable through the Marketplace.
User Widgets are VizChat's long-tail widget extension mechanism — the Agent generates component instances in a conversation, stores them in the database as username/slug@version rows, and other users can browse them in the Marketplace and pull them into their own canvases through chat. No release cycle required.
What is a Widget
- A React/TSX component compiled by the backend into an ESM bundle (inline mount, the default) or a self-contained HTML file (nested mount, runs in an iframe sandbox)
- Generated by the Agent from a conversational request (or authored by developers and published)
- Uniquely identified by the
username/slug@versiontriple - Enriched with tags, description, category, thumbnail, favorite count, and quality / trending scores
User Widget vs built-in widgets
| Dimension | Built-in (BUILTIN) | User Widget (USER) |
|---|---|---|
| Storage | Marketplace listing row + bundle in object storage, loaded at runtime | Same — listing row + bundle in object storage |
| Publishing | Ships with the repo; synced by a build script on release | Any user can publish from the widget editor |
| Scale | ~ten types | Target thousands |
| State access | Depends on mount, not on Built-in vs. User: inline (the default) runs in the canvas's own component tree and can read/write canvas state; nested runs in an isolated iframe | Same — depends on mount |
| Best for | Common, stable, deep canvas integration | Long-tail, one-off, personalized |
How to use
1. Browse the Marketplace
Click the globe icon in the top bar to open /marketplace — it is public, so you can browse it without signing in. Sort by Popular / Trending / Newest / High quality, or search by keyword. A widget's detail page runs a live demo, lets you try the widget on a scratch canvas (select it, resize it, edit its data and settings — changes live only on that page; reset or refresh to start over), shows its docs, and lets signed-in users favorite it; open-sourced widgets also let you download the source package or fork it into your own draft (see below).
2. Pull a widget into the canvas from chat
Type @widget: in the chat input to pick from Marketplace, favorited, and recently used widgets, or write the reference by hand as @widget:<author>/<slug> (optionally @widget:<author>/<slug>@<version>). The Agent then places that widget on the canvas. Simply asking the Agent to add a widget works too.
3. Ask the Agent to generate one
In chat:
"Make me a dice-rolling widget" "Build a 10-minute countdown widget"
The Agent builds the widget directly into the canvas — it doesn't go to the marketplace unless you publish it later.
4. My widgets
When signed in, click the VizChat logo in the top bar to reach your home page /me. Its Creations and Favorites sections list the widgets you've published and the ones you've favorited; each has its own full page at /me/creations and /me/favorites.
If something you favorited was deleted by its author, the card is marked Deleted by author and stops linking anywhere; if it was taken down, it's marked Taken down (takedowns can be reversed, so it stays). Either can be removed individually via the ✕ in the card's top-right corner, and the favorites page has a one-click cleanup that clears only the deleted ones.
Building on an official widget
Every official widget is open-sourced under Apache-2.0. Their detail pages (marked with a green Open source badge next to the title) offer two ways in:
Download source — you get a <slug>-source.zip. Unzipped, it is a complete widget package (package.json, src/, tests, LICENSE, NOTICE). Run pnpm install and develop it locally with the CLI.
Import to my widgets — the server copies the source into a draft under your account and opens the widget editor. Edit, then publish. The package name is rewritten to @<your-username>/<slug> for you.
Both routes give you the same source; the only difference is where you want to edit it — local toolchain, or the in-browser editor.
An import is an independent copy with no link back to the original: changing it does not affect the official widget, and official updates do not flow into your copy. If you already own a widget with that slug, the import is refused rather than overwriting it — rename or delete the existing one in My creations, then retry.
Licensing
Apache-2.0 lets you use, modify, and redistribute the code freely, including commercially, provided you keep the LICENSE and NOTICE files that ship with the package. Both travel with downloads and imports — please don't delete them.
The NOTICE in rich-text carries an additional MIT notice: it embeds styles from Milkdown, and that notice must be preserved too.
Apache-2.0 covers the widget's own source. The @vizchat/* packages it depends on (SDK, UI, build tooling) carry their own license: free to use for developing, building, distributing, and even selling widgets, but you may not redistribute those packages themselves. See the LICENSE inside each package.
Publishing your own widget
Widget publishing shares the authoring workflow with custom widget development. See the Custom widget developer guide.
Tier limits
Widget development is identical across all tiers — see Billing rules and plan limits. BYOK significantly reduces widget iteration cost; see the pricing page for details.
Next step
- Custom widget development — developer-facing widget authoring
- Custom widget guide