Chart types
Choose the chart family that matches the question your data needs to answer.
Choose one of six chart types. 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.
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 |
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, header alignment, and legend preferences are shared.
| 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.
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.