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 me!

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. A single series uses the stacked default because there is no second series to arrange.

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 labels can use auto, inside, or outside; outside keeps zero values visible above their zero-length 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; enable outside stack totals separately with totals: true. Set totals: false or omit it to hide totals. Grouped labels use the same position choices as simple labels; an outside label is not suppressed merely because it is wider than its column band. A numeric label and visible value axis often repeat the same information; for a sparse labeled chart, hiding the value axis is usually cleaner.

Draw one series as a line

line.series names series that are drawn as a line on the same value scale instead of as columns. Use it for a benchmark, a total, or a co-measure that deserves different visual weight.

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

The named series leave the stack or group and read against the shared value axis; the rest keep their geometry. curve, stroke.width, points, and labels style the line and reuse the line vocabulary, while color still comes from the existing series channel, so the legend shows a line glyph for a promoted series and a filled swatch for the others.

series must name at least one member of the effective series domain and may not name every series – that intent is a line chart. Promotion needs an effective series and is unavailable on ranged columns and on percent-normalized arrangements, where a raw-value line against a 0–100% axis would be meaningless.

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. Both are native chart semantics rather than independent drawing layers.

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.