Chart API reference

Every field of a ChartSpec and every chart helper the package exports, each with the page that explains it. The generated reference under /api/ has the full signatures; this page is the map.

The examples on this page import from @svgrid/grid:

<script lang="ts">
  import { SvGrid, SvGridChart } from '@svgrid/grid'
</script>

The spec

A ChartSpec is plain data: a type, the categories along the x axis, one or more series of values, and optional fields that shape the drawing. Pass it to <SvChart spec={...} /> (SvGridChart is the same component under its older name), or hand it to buildChart(spec) for the geometry alone.

<script lang="ts">
  import { SvChart, type ChartSpec } from '@svgrid/grid'

  const spec: ChartSpec = {
    type: 'bar',
    categories: ['Q1', 'Q2', 'Q3', 'Q4'],
    series: [
      { label: 'Plan', values: [40, 45, 50, 55] },
      { label: 'Actual', values: [38, 49, 47, 61], type: 'line', marker: 'diamond' },
    ],
    title: 'Plan against actual',
    yAxis: { min: 0, title: 'Units' },
    valueFormat: 'number',
  }
</script>

<SvChart {spec} legend="right" />

Top-level fields

Series fields

Helpers

buildChart is the one to know when you want the numbers without the drawing: it runs during SSR and in a test.

<script lang="ts">
  import { buildChart, type ChartSpec } from '@svgrid/grid'

  const spec: ChartSpec = {
    type: 'line',
    categories: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
    series: [{ label: 'Visits', values: [120, 132, 101, 134, 190] }],
    width: 480,
    height: 240,
  }
  const geo = buildChart(spec)
  const line = geo.lines[0]!
</script>

<pre style="font-size: 12px; background: var(--sg-bg-subtle); padding: 12px; border-radius: 6px; overflow: auto">
plot: {JSON.stringify(geo.plot)}
y axis: {geo.axes?.y.min} to {geo.axes?.y.max}, ticks {geo.yTicks.map((t) => t.label).join(' ')}
{line.label}: {line.points.map((p) => `(${p.x}, ${p.y})`).join(' ')}
</pre>

Diagnostics

A spec is plain data, and plain data gets typos. validateChartSpec(spec) returns what is off, each with the field's path, a message and a severity: error for what will not draw as intended (a series one value short of the categories, an unknown type, min above max, a log axis pinned at zero, an overlay string the engine does not read), warning for what is ignored or looks like a slip (an unknown key with the nearest known one, a stack on a line series, an annotation naming a category that is not there). It never throws, and a clean spec comes back as an empty array.

The same rules run three ways without being asked. In development, SvChart logs them once per spec object to the console ([SvChart] series[1].values: 2 values for 3 categories; they run in parallel). The MCP server's svgrid_check_code applies them to a spec written as a static literal (a ChartSpec-typed const, a satisfies ChartSpec, or spec={{ ... }} on the tag), with a rename for a misspelt key; a literal with a variable or a call in it is left alone, so a finding is never a guess. And aiChart attaches the errors of the spec it built to its plan as diagnostics.

<script lang="ts">
  import { SvChart, validateChartSpec, type ChartSpec } from '@svgrid/grid'

  // Two slips: a misspelt key and a series one value short.
  const spec = {
    type: 'bar',
    categories: ['Q1', 'Q2', 'Q3'],
    series: [{ label: 'Sales', values: [10, 12] }],
    yAxisTitel: 'Units',
  } as unknown as ChartSpec
  const findings = validateChartSpec(spec)
</script>

<ul style="font-size: 13px">
  {#each findings as f}
    <li><code>{f.severity}</code> <code>{f.path}</code>: {f.message}</li>
  {/each}
</ul>
<SvChart {spec} />

Describing a chart

chartSummary(spec) reads a spec the way a colleague reads the picture: which way each series goes and by how much, where it peaks and troughs, the top three slices of a pie, a scatter's correlation, a candle series' last close and range, a funnel's conversion and its biggest drop. SvChart puts the sentence in the SVG's aria-description and the data table's caption (describe={false} turns that off), the context menu and the grid panel's export menu copy it under "Describe chart", and aiExplainChart(api) grounds its prompt on it before asking the model for two or three insights (the panel's Explain button, once enableAiCharting(api) has run). The words a screen reader hears and the words a model reasons from are the same words.

<script lang="ts">
  import { SvChart, chartSummary, type ChartSpec } from '@svgrid/grid'

  const spec: ChartSpec = {
    type: 'line',
    categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    series: [
      { label: 'Signups', values: [120, 180, 90, 140, 260, 310] },
      { label: 'Churn', values: [40, 42, 38, 35, 30, 28] },
    ],
  }
</script>

<SvChart {spec} />
<p style="font-size: 13px">{chartSummary(spec)}</p>

Live data

A feed hands the chart one point every few hundred milliseconds. The spec is state, and appendPoints(spec, point, { window }) returns the next one: the category and one value per series appended (by index or by series label), every per-category array the series carries (row ids, bands, candles, volumes, colours, markers, errors) grown by the same count with a gap where the point says nothing, and the oldest categories dropped past the window. The input is never mutated. Put live on the chart so the data-update tween and the enter effect stand down: a tween restarted every tick never settles, and an enter effect replays on every tick.

<script lang="ts">
  import { onDestroy } from 'svelte'
  import { SvChart, appendPoints, type ChartSpec } from '@svgrid/grid'

  let price = 100
  let n = 0
  const tick = () => {
    price = Math.max(50, price + (Math.random() - 0.5) * 3)
    return { category: `t${++n}`, values: [Math.round(price * 100) / 100] }
  }
  let spec = $state<ChartSpec>({ type: 'line', categories: [], series: [{ label: 'Price', values: [], smooth: true, marker: 'none' }], yAxis: { title: 'USD' } })
  for (let i = 0; i < 30; i += 1) spec = appendPoints(spec, tick())
  const timer = setInterval(() => (spec = appendPoints(spec, tick(), { window: 40 })), 300)
  onDestroy(() => clearInterval(timer))
</script>

<SvChart {spec} live legend={false} />

The JSON schema

The spec has a JSON Schema, generated from the types: https://svgrid.com/schemas/chart-spec.json (listed in schemas/index.json). Every field carries its doc comment as a description, the chart types and the overlay strings are enumerated, and a function-typed field is marked as one. An editor validates a spec kept in a JSON file against it, an agent asks the MCP server for it (svgrid_get with chart spec schema), and a test in the repo keeps it equal to KNOWN_SPEC_KEYS and CHART_TYPES.

{
  "$schema": "https://svgrid.com/schemas/chart-spec.json",
  "type": "bar",
  "categories": ["Q1", "Q2", "Q3", "Q4"],
  "series": [{ "label": "Plan", "values": [40, 45, 50, 55] }]
}

Component props

The component's props (legend, dataLabels, zoomable, tooltip, selectable, localeText and the rest) are on the SvGridChart props page; SvChartPanes has its own, and the <sv-chart> element's attributes are generated from the same list.

<script lang="ts">
  import { SvChart, type ChartSpec, type ChartSelection } from '@svgrid/grid'

  const spec: ChartSpec = {
    type: 'pie',
    categories: ['Direct', 'Search', 'Referral', 'Social'],
    series: [{ label: 'Visits', values: [38, 27, 22, 13] }],
    innerRadius: 0.5,
  }
  let picked = $state<ChartSelection | null>(null)
</script>

<SvChart {spec} dataLabels={{ placement: 'outside' }} legend={false} onSelect={(s) => (picked = s)} />
<p>{picked ? `${picked.category}: ${picked.value}` : 'Click a slice.'}</p>

More examples

Every chart type

Every chart type from one dataset, thirty live thumbnails: bar, horizontal bar, line, area, lollipop, dumbbell, range bar, range area, pareto, radial column, radial bar, nightingale, pie / donut, tree map, sunburst, funnel, waterfall, sankey, chord, radar, heat map, scatter, box plot, histogram, gauge, bullet, calendar, stream, candlestick and OHLC. Click a card for the full-size chart and its variants: classic / hollow / Heikin-Ashi candles, funnel / pyramid / cone, wiggle / silhouette streams, stacking. Every spec is built with the helpers the grid chart panel uses.

Combination charts

Revenue and cost as bars, gross margin as a smooth line on its own right-hand axis formatted as a percent, a margin target drawn on that axis, cost switchable to an area, a margin line that is smooth or straight, data labels on the revenue bars only through a formatter, and a shared tooltip that lists every series for the hovered month.

Built-in charting: custom buildSpec

When group-by / split-by can't express the chart, charting.buildSpec hands you the current rows and you return any ChartSpec - here a custom sankey rendered right in the built-in Chart panel. Filter the flow table and the ribbons redraw.

See also

• Getting started
• SvGridChart props
• The generated API reference