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. Range values do not stack, group, normalize, aggregate, or introduce a series; spacing, color, corners, strokes, and axes remain ordinary bar presentation.

Labels and corners

Native labels understand bar length, stacking, series identity, and contrast. Simple and grouped labels can use auto, inside, or outside; an outside label is not suppressed merely because it is taller than its bar band, and a zero-value label stays visible to the right of its zero-length bar. Stacked segment labels stay centered inside and disappear when they do not fit; totals: true adds a separate outside total. Set totals: false or omit it to hide totals. cornerRadius changes only the exposed end corners 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 names series that are drawn as a line on the same value scale instead of as bars. 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 bars and on percent-normalized arrangements, where a raw-value line against a 0–100% axis would be meaningless.

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