Legend

The legend lives at legend on chartData. It controls series colors (legend.colors), visibility, typography, item order, and placement (docked slots or free-floating).

legend: {
  visible: true,
  position: 'rightTop', // docked slot, or 'free'
  orientation: 'vertical', // item flow: 'vertical' | 'horizontal'
  reverseOrder: false,
  colors: ['#4285F4', '#DB4437', '#F4B400'],
  itemVisibility: {},
  text: {
    fontSize: 11,
    fontColor: 'black',
    fontFamily: 'Arial',
  },
  // When position is 'free' only:
  // x: 0.55,
  // y: 0.08,
}

legend.orientation is item layout (stack vs row). It is not orientation on the chart (axes / bars). Flipping the chart does not flip the legend.

---

Placement model

Two modes, both via legend.position:

Mode	position	Plot space	Coordinates
Docked	One of 12 slots below	Reserves margin (width on left/right, height on top/bottom)	Engine places the legend; x / y are rewritten on draw — do not treat them as source of truth
Free-floating	'free'	Does not reserve margin (overlays the plot)	x / y are fractions of the drawable chart area (roughly 0–1)

There is no separate dock / placement field.

Docked positions (12)

Side first, then alignment:

Side	Values
Top	topLeft, topCenter, topRight
Bottom	bottomLeft, bottomCenter, bottomRight
Left	leftTop, leftCenter, leftBottom
Right	rightTop, rightCenter, rightBottom

Default is rightTop.

// Bottom strip
legend: {
  visible: true,
  position: 'bottomCenter',
  orientation: 'horizontal',
}

// Left rail
legend: {
  visible: true,
  position: 'leftTop',
  orientation: 'vertical',
}

Free-floating

legend: {
  visible: true,
  position: 'free',
  orientation: 'horizontal', // author-controlled; not tied to a dock
  x: 0.55,
  y: 0.08,
}

Precise x / y are easiest to set by dragging in edit mode, then exporting config. Free legends can overlap series or labels because they do not push the plot.

---

Orientation (item flow)

Value	Layout
vertical	Items stack top → bottom (default; fits left/right docks)
horizontal	Items flow sideways, may wrap (fits top/bottom docks)

When you drag the legend onto a dock in the editor, orientation is updated automatically:

Dock family	Forced orientation
top* / bottom*	horizontal
left* / right*	vertical
free	unchanged

Hand-authored / API patches that only change position do not auto-update orientation. Always set a matching orientation when docking by config — e.g. bottomCenter + leftover vertical yields a tall legend on the bottom strip.

---

Visibility and items

Field	Role
visible	Whole legend on/off
itemVisibility	Per-series map: { "0": false } hides series 0 from the legend. Missing key or true = shown
reverseOrder	true reverses series order in the legend

Defaults: legend starts hidden on waterfall, bar mekko, and pie/donut; shown on other types. Single-series charts often look cleaner with visible: false.

Hiding the last visible legend item also turns the whole legend off. Showing the legend again when every item was hidden clears itemVisibility.

---

Colors and text

Field	Role
colors	Series / category fill palette (shared with the chart)
text.fontSize / fontFamily / fontColor	Legend label typography

See also Colors & fonts.

---

Field reference

Field	Type	Default	Notes
visible	boolean	type-dependent	See above
position	string	'rightTop'	12 docks or 'free'
orientation	'vertical' | 'horizontal'	'vertical'	Item flow; match dock family when hand-authoring
x / y	number	0.13 / 0.05	Used when position === 'free'
reverseOrder	boolean	false
colors	string[]	org palette	Series fills
itemVisibility	object	{}	Keys are series index strings
text.fontSize	number	11	pt
text.fontColor	string	'black'
text.fontFamily	string	org default

---

Tips

• Docked legends reserve plot space; free legends overlay it.
• On horizontal charts, left/right docks compete with category labels for width — bottom or free often works better, or hide the legend.
• Prefer edit-mode drag + exportConfig() / getChartData() when you need exact free placement or a precise dock alignment.