Chart types
Choose the chart family that matches the question your data needs to answer.
Choose a chart type for the story your data tells. Each defines the data roles, labels, references, annotations, color behavior, and presentation options appropriate to that chart.
Column
Vertical categorical comparisons.
Bar
Horizontal categorical comparisons and ranked lists.
Line
Ordered trends and change over time.
Area
Magnitude or composition over an ordered category.
Scatter
Relationships between two measures.
Pie
Compact part-to-whole comparisons.
Waterfall
Signed steps from an opening to a closing balance.
Choose by question
| Question | Start with |
|---|---|
| How do categories compare? | Column |
| Are labels long, or is rank the point? | Bar |
| How does a measure change over an ordered dimension? | Line |
| How does magnitude or composition change over time? | Area |
| How do two measures relate? | Scatter |
| How is one total divided into a few parts? | Pie |
| How did one balance change step by step? | Waterfall |
Orientation, labels, and decoration do not create a new family. A donut is a pie with innerRadius; a grouped comparison is a column or bar with a series role and arrangement: { type: "grouped" }.
Shared fields
Every config uses the current version and one chart type. Titles, caption, accessibility text, locale, theme, theme overrides, and header alignment are shared; legends belong to each chart type’s color or size.
| Field | Type | Default | Description |
|---|---|---|---|
version | "2026-09-26" | – | Required. The chart config version. |
type | ChartType | – | Required. The chart family. |
title | string | – | Chart title. |
subtitle | string | – | Supporting text beneath the title. |
caption | string | – | Caption below the chart for a source, methodology note, or date. |
accessibilityDescription | string | – | Accessible description of the chart's meaning. |
headerAlign | "start" | "center" | "end" | theme default | Horizontal alignment for the title and subtitle. Omit it to use the selected theme's alignment. |
locale | string | "en-US" | Locale identifier accepted by JavaScript Intl and associated with the chart content, such as en, pl, or zh-Hant. |
theme | ThemeName | "editorial" | One of 6 built-in themes. |
themeOverrides | ThemeOverrides | – | Override individual theme properties. |
The chart-type pages list every additional field. Optional values should usually be omitted so Szum and the selected theme can apply their designed defaults.
Draw one series as a line
Column, bar, and area charts can draw named series as a line on the shared value scale with line.series, for a benchmark, a total, or a co-measure that deserves different weight:
{ "line": { "series": ["Active paying"], "curve": "monotone" } }The named series leave the stack or group and read against the same value axis; the rest keep their geometry. curve, stroke.width, points, and labels style the line with the line vocabulary. Color still comes from the series, and the legend shows a line glyph for a promoted series.
The rules:
- The chart needs a series: a long or count
series, or at least two wide fields. seriesnames existing series, at least one, and never all of them; promoting every series is a line chart.- Percent-normalized stacks cannot promote, because a raw-value line on a 0–100% axis means nothing. Absolute stacks can.
- Ranged columns and bars cannot promote.
Native additions
Use labels for repeated data values or identities, reference lines for fixed targets and calculated statistics, and annotations for explanatory notes anchored in data space. Each chart type defines the supported forms, and Szum keeps them consistent across SVG, PNG, embeds, Studio, MCP previews, and Figma.
{
"text": "Worth highlighting",
"anchor": { "type": "category", "category": "Jan" },
"placement": { "side": "left", "align": "center", "gap": 36 },
"connector": "line"
}Sides are above, right, below, and left. Alignment is start, center, or end along that side. Category placement follows the whole visible category as filtering changes its shape.
See Annotations for anchor and placement behavior, Reference lines for targets and statistics, the Cookbook for complete patterns, and older config compatibility if you use a 2026-03-20 mark-based config.