Bar charts

bar is the horizontal categorical family. It uses the same category and value roles as column, but gives labels more horizontal room and makes top-to-bottom ranking natural.

Ranked comparison

 1{
 2  "version": "2026-09-26",
 3  "config": {
 4    "version": "2026-09-26",
 5    "title": "Team headcount",
 6    "type": "bar",
 7    "category": {
 8      "field": "team"
 9    },
10    "values": {
11      "type": "long",
12      "field": "people"
13    },
14    "order": {
15      "type": "value",
16      "direction": "descending"
17    },
18    "labels": {
19      "content": [
20        "value"
21      ]
22    },
23    "valueAxis": false,
24    "theme": "editorial"
25  },
26  "data": [
27    {
28      "team": "Engineering",
29      "people": 42
30    },
31    {
32      "team": "Sales",
33      "people": 26
34    },
35    {
36      "team": "Customer success",
37      "people": 18
38    },
39    {
40      "team": "Design",
41      "people": 12
42    },
43    {
44      "team": "Product",
45      "people": 8
46    }
47  ],
48  "presentation": {
49    "background": "opaque",
50    "colorScheme": "system",
51    "systemFallback": "light"
52  }
53}

For ranking, sort by value and place the largest category first. An explicit category list is better when the order has domain meaning, such as funnel stages or survey responses.

Grouped and stacked bars

Use a series role or wide values for multiple series. arrangement: { type: "grouped" } compares series directly; { type: "stacked" } emphasizes totals and composition.

Ranged bars

Use values.type: "range" for durations and intervals that have a start and end but no central estimate. A ranged bar is horizontal; use column for the vertical orientation. The category scale is band, while the value scale may be linear, log, or UTC.

{
  "type": "bar",
  "category": { "field": "phase" },
  "values": {
    "type": "range",
    "start": { "field": "startsAt" },
    "end": { "field": "endsAt" },
    "scale": { "type": "utc" }
  }
}

Every end must be after its start. Ranged bars have no series, stacking, grouping, normalization, aggregation, labels, references, or annotations, and sort only by category or an explicit list. Spacing, color, corners, strokes, and axes work as on ordinary bars.

Labels and corners

Category names sit to the left of the bars. When the longest name would take more than 30% of the chart’s width, they move above their bars instead, starting where each bar starts, so the bars keep the full width. Names longer than the chart wrap onto a second line; the category axis line then only appears if you set categoryAxis: { line: true }.

Native labels account for bar length, stacking, series, and contrast. Simple and grouped labels can use auto, inside, or outside. An inside label sits at the end of its bar, where the eye finishes reading the length; an outside label is not dropped just because it is taller than its bar, and a zero value stays visible to the right of its zero-length bar.

Stacked segment labels stay centered inside and disappear when they do not fit. A stack with only one segment per bar, such as a single series, labels its bars at the end like a simple bar chart; totals: true adds an outside total, and omitting it or setting false hides totals. cornerRadius rounds only the exposed ends, so stacked segments still meet cleanly.

Use labels selectively on dense grouped charts. A shared value axis may communicate comparison more clearly than printing every number.

Draw one series as a line

line.series draws the named series as a line on the same value scale instead of as bars, 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 bars and percent-normalized stacks. See promoted lines for the full rules.

References and annotations

Fixed reference lines work well for targets or service-level thresholds; calculated references can follow the average, median, minimum, or maximum of visible or all data. Category references identify a particular band. Attach an annotation to a category and series when it should follow that datum through updates and filtering; use { type: "coordinate", category, value } for an exact position.

Properties