Skip to content

API reference

import {
  plot, safePlot, lint, describe, render, toHTML, configure,
  dashboard, safeDashboard, renderDashboard, lintDashboard, planDashboard,
  schema, dashboardSchema, toolDefinition, validatePalette, registerGeo, countWords,
} from 'plotagents';

Full types are in index.d.ts and every spec option in schema.json.

Drawing

plot(spec)

Draws a chart and returns an SVG string. Works in Node, Deno, Bun and the browser. Throws a PlotError when the spec cannot be drawn; the error's hint says how to fix it.

const svg = plot({ type: 'bar', data, x: 'region', y: 'sales', title: 'Biobío leads with 30%' });

safePlot(spec)

The version to expose as an agent tool: it never throws.

const { ok, svg, type, description, errors, warnings, suggestions } = safePlot(spec);
FieldMeaning
oktrue when the chart was drawn.
svgThe SVG string, or null.
typeThe resolved chart type (useful when type was inferred).
descriptionAlt text for the chart.
errorsProblems that stop the chart: { code, message, fix }.
warningsProblems that make the chart misleading or hard to read.
suggestionsDesign improvements, such as a better title or highlight.

lint(spec)

Reviews a spec without drawing it and returns { ok, type, errors, warnings, suggestions }. Messages follow the spec's locale (Spanish by default, English with locale: "en"); each one carries a fix with the change to make.

dashboard(spec) · safeDashboard(spec) · renderDashboard(el, spec)

A self-contained HTML dashboard with best-practice layout, shared colors, KPIs and filters. safeDashboard never throws and returns { ok, html, plan, errors, warnings, suggestions }; renderDashboard draws into an element in the browser; lintDashboard reviews; planDashboard returns the layout decisions. See Dashboards.

describe(spec)

Returns a text description of the chart, such as "Highest: Biobío with 1,240 (30%)…". The same text goes into the SVG's <desc> for screen readers.

In the browser

render(target, spec, opts?)

Draws into an element (a CSS selector or a DOM node) with tooltips, responsive width, time controls when the spec asks for them (slider: true), drill-down for treemaps and sunbursts, click-to-focus for networks, collapsible Gantt phases, and legend clicks (shift + click excludes an entry; in treemaps and sunbursts a click zooms to the category).

const chart = plotagents.render('#chart', spec);
chart.update({ ...spec, highlight: 'Ñuble' });   // redraw
chart.destroy();                                // remove listeners and markup
OptionMeaning
controlsfalse hides time controls even when the spec asks for them (slider: true).

The handle exposes svg (the current <svg> element) and spec.

attach(root)

Adds tooltips to a container that already holds a plotagents SVG, for example one rendered on the server.

toHTML(specs, opts?)

A self-contained HTML page with one or more interactive charts. Only the library modules the page needs are inlined (its chart types and map geometries), and shared data goes in once.

OptionDefaultMeaning
title"Gráficos"Page title.
lang"es"Page language.
columns1Two or more lay charts out in a grid.

Configuration

configure(options)

Sets defaults for every later chart; the spec always wins.

configure({ font: 'Poppins', textScale: 1.5, locale: 'en' });
configure();       // returns the current defaults
configure(null);   // clears them

It accepts any spec option: font, textScale, locale, theme, palette, ramp, colorScale, legend and so on. A spec's own theme object is merged over the global one.

registerTheme(name, theme)

Registers a named theme (merged over extends, papel by default) so theme: name and configure({ theme: name }) can use it. See Themes.

registerTheme('acme', { background: '#FFF', text: '#111', categorical: 'tab10', grid: { dash: '2 3' } });
configure({ theme: 'acme' });

colorScaleNames() · resolveColorScale(name)

All color scale names grouped by kind (sequential, diverging, cyclic, qualitative), and the stops of one scale: { name, stops, kind }. interpolateColor(stops, t) returns the color at t ∈ [0, 1] (OKLab).

validatePalette(colors, opts?)

Checks a custom palette with the same tests the built-in one passes. See themes.

validatePalette(['#223C6A', '#E69B0A', '#D21428'], { mode: 'light', surface: '#FFFFFF' });
// → { ok: false, checks: [{ name: 'lightness', status: 'fail', detail: '…' }, …] }

registerGeo(name, featureCollection, aliases?)

Registers your own GeoJSON so specs can use geo: name. Chile and the world are built in.

For agents

toolDefinition({ name?, flavor? })

Returns a tool definition built from the JSON Schema: flavor: "anthropic" (default) gives { name, description, input_schema }, flavor: "openai" gives { type: "function", function: { … } }.

import Anthropic from '@anthropic-ai/sdk';
import { safePlot, toolDefinition } from 'plotagents';

const client = new Anthropic();
const res = await client.messages.create({
  model: process.env.ANTHROPIC_MODEL,
  max_tokens: 4096,
  tools: [toolDefinition()],
  messages: [{ role: 'user', content: 'Plot the distribution of service times per clinic: …' }],
});
const call = res.content.find((b) => b.type === 'tool_use');
const { ok, svg, errors } = safePlot(call.input);
// If !ok, send `errors` back as the tool_result: every error carries a `fix`.

schema

The JSON Schema of a spec, also published as schema.json and importable as plotagents/schema.json.

Helpers

ExportMeaning
TYPESEvery chart type name.
themes, getTheme(t), themeFor(spec)Built-in themes and the resolved theme of a spec.
palettes, rampsNamed categorical palettes and sequential/diverging ramps.
timeValues(spec)Sorted values of the time field.
makeFormat(fmt, locale, values)The number formatter a chart would use.
formatNumber(v, decimals, locale), formatCompact(v, locale)Locale-aware number formatting.
squarify(items, x, y, w, h)The treemap layout algorithm.
bundleSource()Node only: the browser build as a string, for inlining.

Package entry points

ImportContents
plotagentsEverything above (ES module).
plotagents/coreplot(), configure(), themes, skins and every chart type except maps and tables. No bundled geometries, lint, schema or dashboards: for bundlers without tree-shaking.
plotagents/types/<file>The base plus one family: line (line, area), bar (bar, column, count), scatter, treemap, sunburst, donut, dist, regplot, categorical, radar, network, chord, pyramid, flowchart, gantt, wordcloud, heatmap, corr, sankey, kpi. Import several to combine them.
plotagents/mapsThe base plus choropleth, symbolmap, pointmap and registerGeo(), without the bundled geometries: pass your own GeoJSON/TopoJSON.
plotagents/tableThe base plus table.
plotagents/schema.jsonThe JSON Schema.
plotagents/browserdist/plotagents.js: a <script> that defines window.plotagents.
plotagents/browser/geodist/plotagents-geo.js: Chile and world geometries for the browser build.
plotagents/geo/chile, plotagents/geo/worldThe geometries as ES modules.

Edit this page on GitHub