Clustered bar

Side-by-side bars that compare series within each category.

Identity

chartType	clusteredBar
Option bag	bar
seriesData layout	seriesRows – row 0 = category header; later rows = series
Min grid	2 rows × 2 columns (header included)
Orientation	Yes – vertical (default) or horizontal
Sample	Clustered bar · Horizontal bar

---

Minimal chartData

{
  chartType: 'clusteredBar',
  isDataTransposed: true,
  seriesData: [
    ['', 'Q1', 'Q2', 'Q3', 'Q4'],
    ['Revenue', 100, 112, 125, 140],
    ['Costs', 60, 66, 70, 78],
  ],
  title: { visible: true, text: 'Revenue vs Costs' },
  subtitle: { visible: false, text: '' },
}

---

seriesData

With isDataTransposed: true (usual):

[
  ['', 'Q1', 'Q2', 'Q3'],       // categories
  ['Revenue', 100, 112, 125],   // series 0
  ['Costs', 60, 66, 70],        // series 1
]

Rule	Detail
Row 0	Category labels (after the corner cell)
Later rows	One series each; first cell is the series name
Cells	string | number | boolean | null
Ragged rows	Warn, still load – pad when columns must align

Shared layout rules: chartData schema · seriesData.

---

Option bag: bar

clusteredBar, stackedBar, and stackedBar100 all read cd.bar. Stacking / 100% behaviour comes from chartType, not from a different bag.

Field	Default (new charts)	Role
padding	0.3	Gap between bars / clusters, 0–1
cornerRadius	0	Bar corner radius (px)
reverseStackOrder	false	Stack order (mainly stacked types; harmless on clustered)
seriesStrokes / seriesStrokeWidths / seriesStrokeDashArrays	[]	Per-series stroke chrome
series	[]	Per-series / per-point override slots
overrides	–	Indexed style patches

{
  chartType: 'clusteredBar',
  seriesData: [/* … */],
  bar: {
    padding: 0.2,
    cornerRadius: 2,
  },
}

---

Axes & scales

Role	Vertical (default)	Horizontal
Domain (categories)	bottom	left
Primary range (values)	left	bottom

• Keep 0 in range for honest bar lengths (engine bias for bars).
• Format / tick interval / gridlines on the primary range side after orientation.
• Secondary axis is uncommon on pure clustered bars; use combo or dual-axis line when units differ.

Details: Axes · by chart type · Value axis · Orientation.

Horizontal

{
  chartType: 'clusteredBar',
  orientation: 'horizontal',
  isDataTransposed: true,
  seriesData: [/* same layout */],
  title: { visible: true, text: 'Pageview Sources' },
  subtitle: { visible: false, text: '' },
  legend: { visible: false },
}

After the flip, put value formats and preferredTickInterval on axes.bottom, not axes.left. Live: Horizontal bar sample.

---

Type-specific behaviour

• Palette lives on legend.colors, not on the bar bag.
• Category totals default on. Hide them with annotations.totals.visible: false – see Labels. Do not invent showTotalLabels.
• Data labels / series emphasis are mostly annotation and override trees – polish in the editor, then getChartData().
• Changing to stackedBar / stackedBar100 keeps the same seriesData shape and the same bar bag; only the type (and axis % defaults for 100%) change.

---

Pitfalls

• Using the line or area bag on a bar chart – rejected as foreign-option-bag
• Formatting axes.left after setting orientation: 'horizontal' (range moved to bottom)
• Pinning customMin above zero so bars look taller than the data
• Expecting reverseStackOrder to change clustered side-by-side order in a meaningful way – it targets stacks
• Wrong seriesData orientation (isDataTransposed: false) without matching the grid

---

Related

• Stacked bar / 100% · Combo
• chartData schema · Axes · Legend
• Samples: Clustered bar · Horizontal bar · Currency ticks