Custom visuals from HTML
Add a chart your dashboards don't have, written as one HTML file, with no build or publish step
Add a chart your dashboards don't have, such as a sankey, a bullet chart or a calendar heatmap, as one HTML file. Any AI assistant can write it from the prompt you copy in the editor; you paste the result into the card. There is nothing to build, install or publish.
The visual draws the card's own data, with the dashboard's filters and your users' permissions already applied and every value already formatted. It follows your brand in light and dark mode, adapts to the card's size, and prints in PDFs and scheduled reports. If it ever fails, the card shows its data as a table instead.
Add one in the editor
Open a card in the editor and pick Custom visual, the last entry in the chart picker. The card keeps its query, written in either drag-and-drop or SQL. Then start in whichever way suits you:
- Describe it. Type what you want to see, such as "a sankey of requests from actor type to surface to outcome", and click Build. The assistant opens beside the editor, builds the visual from your card's fields, and puts it in the card. To change it, ask the assistant. This is available when the assistant is turned on for your project.
- Start from a template. Pick a Sankey, Calendar heatmap, Gauge, Waterfall, Small multiples or Progress list. It fills from your card's fields and draws right away.
- Use your own assistant. Click Copy prompt, which copies the visual contract and your card's fields, give it to Claude, ChatGPT or any assistant with what you want, then click Paste code and paste the HTML it writes.
However you start, the panel then shows the visual's Fields (which of your card's fields go into each of its slots) and its Settings, both from the visual's own manifest. Its Code is there to copy or replace. Save the dashboard to keep it.
Before a visual can be saved, it is rendered at several sizes in light and dark mode:
- Problems that block saving: it throws an error, never says it's ready, draws nothing, or tries to reach the network. The editor lists each one with what to change; paste a fixed version.
- Warnings that don't block: text below 4.5:1 contrast, content cut off at small sizes, your brand font not used, or colours written into the code.
How a visual works
The contract you copy says everything an assistant needs. In short:
- One HTML document, at most 256 KB. Chart libraries load from jsDelivr, cdnjs or unpkg with an exact version in the URL; nothing else can be fetched.
- A manifest at the top declares the visual's name, its slots (what it draws: dimensions and measures) and its settings (switches, numbers, text, choices and colours).
- Slots fill by position. Your card's dimensions go into dimension slots and its measures into measure slots, in order. Renaming a field or swapping a measure keeps working. You can reassign any slot in the editor.
- Data arrives formatted. Each value comes as
{ value, text }, wheretextis formatted exactly as the card's table would show it. A value with nothing in it is a gap, never a zero. - Measures say whether they add up. A sum or a count does; an average, a ratio or a distinct count doesn't, so a visual that adds rows (a Sankey, a waterfall) asks for a sum or a count instead.
- Theme variables (
var(--sv-fg), the palette, the brand font) keep the visual in your brand in light and dark mode. semaphor.ready()after drawing tells the dashboard the visual is done, so PDFs wait for it. A chart library that finishes later callssemaphor.ready(payload)with the data it drew.
The visual runs in a sandbox. It can't read the page, its cookies or any API; it never sees a token or a query, only the rows its card returns for the person viewing it.
Where visuals live
A custom visual belongs to the dashboard it was added to. Duplicating the dashboard copies its visuals. Each save of changed code keeps the earlier version, and an unchanged visual isn't saved again.
With AI agents
Agents that use the Semaphor MCP server build custom visuals the same way you do. They read the contract and the card's fields, write the HTML, and propose the card, including on a new, empty card. The proposal is checked like a save in the editor, so an agent gets the same fix list and fixes the code before you review the change. Once you approve it, the agent and the editor save the same card.
Custom visuals from HTML or React plugins
Use HTML visuals for a chart one dashboard needs, written in minutes by an assistant. Use React plugins when you need a visual library shared across projects, built and versioned in your own repository.