Column charts

Use column when categories fit comfortably on the horizontal axis and comparison by length is the main task. For long labels or a ranked list, use bar.

Basic comparison

 1{
 2  "version": "2026-09-26",
 3  "config": {
 4    "version": "2026-09-26",
 5    "title": "Quarterly revenue",
 6    "type": "column",
 7    "subtitle": "USD thousands",
 8    "category": {
 9      "field": "quarter"
10    },
11    "values": {
12      "type": "long",
13      "field": "revenue"
14    },
15    "labels": {
16      "content": [
17        "value"
18      ]
19    },
20    "valueAxis": false,
21    "theme": "editorial"
22  },
23  "data": [
24    {
25      "quarter": "Q1",
26      "revenue": 42
27    },
28    {
29      "quarter": "Q2",
30      "revenue": 58
31    },
32    {
33      "quarter": "Q3",
34      "revenue": 65
35    },
36    {
37      "quarter": "Q4",
38      "revenue": 81
39    }
40  ],
41  "presentation": {
42    "background": "opaque",
43    "colorScheme": "system",
44    "systemFallback": "light"
45  }
46}

Edit to update the chart

category names the discrete or ordered category field. values reads one field with type: "long", several fields with type: "wide", or counts rows.

For vertical start/end intervals, use values.type: "range" with start.field and end.field. Range values may use linear, log, or UTC scales and follow the same strict ordering rules as ranged bars.

Multiple series

Add values.series to long values, or use wide values. arrangement controls whether series stack or sit side by side.

Stacking emphasizes the total and composition; grouping emphasizes individual series values. With a series, omitting arrangement stacks. Without one, the chart is a simple column chart and takes no arrangement.

Ordering and labels

Use order: { type: "value", direction: "descending" } to rank categories, or an explicit category list when domain order is part of the story.

Simple and grouped labels can use auto, inside, or outside. Inside places the label at the top of its column, where the height ends. Outside keeps a zero value visible above its zero-length column, and an outside label is not dropped just because it is wider than its column.

Stacked labels can contain value, percent, category, and series. They stay centered inside their segment and are omitted when the segment is too thin. A stack with only one segment per column, such as a single series, places its labels at the top of the column instead. Add outside stack totals with totals: true; omit it or set false to hide them.

A value label and a visible value axis often say the same thing twice. On a sparse labeled chart, hiding the value axis is usually cleaner.

An outside label can extend beyond its column band, but it is omitted with a render warning if its measured text cannot fit within the chart canvas. For very long numbers, choose a concise values.format or increase the chart size.

Draw one series as a line

line.series draws the named series as a line on the same value scale instead of as columns, for a benchmark, a total, or a co-measure:

{ "line": { "series": ["Active paying"], "curve": "monotone" } }

It needs a series, cannot name every series, and is unavailable on ranged columns and percent-normalized stacks. See promoted lines for the full rules.

References and annotations

Reference lines add category- or value-axis rules. A value rule may use a fixed target or derive an average, median, minimum, or maximum from visible or all data; derived rules may select one series. An annotation can attach to a category and series so it follows that segment and disappears with legend filtering. Use { type: "coordinate", category, value } only for an exact authored position. Ranged columns take neither.

Use { type: "category", category: "Q3" } to follow the whole category as visible series change. Notes make room by default: their boxes may move to avoid chart text, and Auto or "shape" widths may rewrap to fit. Numeric widths stay exact. A note that cannot be placed produces a diagnostic while its definition remains intact. Set reserveSpace: false for an exact overlay, accepting possible overlap or clipping.

Properties

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.
`category`	BarCategoryRole \| RangeCategoryRole	`–`	Required. Category field; band or UTC scales for scalar bars, and band scales for ranges.
`values`	ValuesRole \| RangeValuesRole	`–`	Required. Long, wide, count, or start/end range values.
`arrangement`	BarArrangementPreference	`stacked for series values`	Stacked or grouped placement for series values; percent normalization belongs to the stacked branch. Omit for simple and ranged bars.
`order`	CategoryOrder \| RangeCategoryOrder	`–`	Category/value sorting or explicit order for scalar bars; ranges support category sorting or explicit order.
`spacing`	BarSpacingPreference	`–`	Category spacing; series spacing is available only for grouped bars.
`color`	CategoricalColor	`–`	Categorical color preferences.
`categoryAxis`	boolean \| AxisOptions	`–`	True shows the category axis, false hides it, and an options object shows it with those settings. Omit for defaults.
`plotBorder`	boolean	`theme default`	Full plot border, independent of axis visibility.
`valueAxis`	boolean \| AxisOptions	`–`	True shows the value axis, false hides it, and an options object shows it with those settings. Omit for defaults.
`annotations`	CartesianAnnotation[]	`–`	Positioned annotations for scalar bars.
`references`	CategoricalReference[]	`–`	Reference lines for scalar bars.
`cornerRadius`	number	`theme default`	Column end-corner radius.
`stroke`	Stroke	`–`	Column stroke color and width.
`labels`	StackedBarLabels \| PositionableBarLabels	`–`	Scalar column labels: stacked content, or simple/grouped content and position.
`totals`	boolean	`–`	Show or hide totals for unnormalized stacked columns. Omit to hide.
`line`	PromotedLine	`–`	Draw named series as a line on the same value scale instead of bars or areas. "series" is a non-empty subset of the effective series domain and may not name every series; use type "line" for that. Unavailable on ranged bars and on percent-normalized arrangements.