Html

Build fully custom, interactive visualizations with HTML and JavaScript — including D3, Chart.js, Observable Plot, or any JS charting/graphics library. This is a first-class way to create bespoke charts, diagrams, and widgets the built-in components don’t cover; reach for it whenever someone asks for D3 or a custom/complex visualization, and honor the specific library they name. The tag body is HTML; any <script> runs in a secure isolated sandbox. Data is PULL-based (there is no data= attribute): fetch a named query’s rows with await evidence.query("query_name"), where the query is declared elsewhere on the page as a SQL file or inline sql block — multiple queries can be used in one block. To pass page-level values (frontmatter, repeat scope, filter results, literals) into the iframe, use a `variables={…}` attribute on the tag — `{% html variables={ name=$customer region=region_filter.value limit=10 } %}` (Markdoc object syntax: whitespace-separated `key=value`, no commas) — and read them inside the block as `evidence.variables.name`, etc. Reactive: when a value changes (e.g. the user changes a filter), `evidence.onVariablesChange(cb)` and `evidence.subscribe(cb)` fire so the author can re-render. The author-facing API lives under a single `evidence` namespace: `evidence.query(name)` → rows; `evidence.variables` → values passed via the `variables=` attribute; `evidence.onVariablesChange(cb)`; `evidence.theme` → { mode, palette }; `evidence.onThemeChange(cb)`; `evidence.subscribe(cb)` → re-render on any filter/theme/variable change; `evidence.filters.get()/.set(id, value)/.subscribe(cb)` for cross-filtering, and `evidence.filters.create(id, initialValue)` to declare your OWN page filter (e.g. a custom dropdown) that you reference from any sql query with {{ id }}/{{ id.selected }} (quoted) or {{ id.literal }} (raw), exactly like a built-in input — .create it first, then .set it on interaction (.set alone only works on a filter that already exists); pass evidence.filters.create(id, initialValue, { column: "the_column" }) to bind it to a column so it auto-applies to BUILT-IN charts via their filters="id" prop (it emits a real column = value/IN (…) predicate, just like a built-in dropdown); evidence.ready() to signal the first render is complete (call it after async draws so PDF/PNG export captures a finished frame). Load libraries from one of the allowlisted CDNs (esm.sh, esm.run, cdn.jsdelivr.net, unpkg.com, cdnjs.cloudflare.com, d3js.org). For ES modules use a module script: <script type="module">import * as d3 from "https://esm.sh/d3@7"</script> (a bare import in a classic <script> is a syntax error). Classic inline <script> supports top-level await. For data from the user’s page, ALWAYS use evidence.query("query_name") — page rows live in the parent and have no public URL to fetch. External public data is reachable: fetch, XHR, d3.csv, and d3.json work against a curated network allowlist that covers common analytical hosts (map tile servers, data CDNs, keyless public-data APIs like World Bank, Open-Meteo, REST Countries, Frankfurter currency, and Statistics Canada). See the “Network Allowlist” section of the html docs page for the full, current list. Other hosts are blocked — if blocked, switch to a query against a connected source, or surface the host to the user so they can request a project-level allowlist. Put render logic inside <script> and, if it should react to filter/theme changes, wrap it in evidence.subscribe(render). By default the block autosizes to its content height (and fills the page width), growing and shrinking as the content does — so give your content a real height: a fixed-pixel element, or a responsive SVG sized with viewBox + width:100% + height:auto (which gets its height from the aspect ratio). A height:100% element has nothing to fill in autosize mode, so for charts that fill a fixed box (canvas/ECharts/Chart.js read the container size) pass height= (pixels) — that pins the box AND makes the mount area full-height so height:100% works. The block resizes its width with the page, but a chart only reacts if you make it responsive: scale SVGs with viewBox + width:100% (no redraw needed), or redraw from evidence.onResize(cb) (call the library’s resize in the callback for canvas/ECharts/Chart.js). Never hardcode a pixel width and expect it to reflow. Tooltips/popovers are clipped at the block edges (it’s an isolated frame — CSS overflow can’t escape it), so position them relative to your container and clamp into bounds — left = Math.max(0, Math.min(x, mount.clientWidth - tip.offsetWidth)), same for top — or flip near an edge, so they never get cut off.