Skip to main content
The legend section controls where the legend sits and how it presents groups. A legend appears when a chart maps a visual aesthetic such as color or size. Under position: 'auto', a legend with a single item is dropped on bar, line, area and polar graphs.

​
Options

​
'auto' | 'top' | 'bottom' | 'left' | 'right' | 'none'
default:"auto"
Where the legend sits. 'none' hides it. 'auto' resolves to 'right' for a line, area or unflipped stacked bar graph with three or more items, and to 'top' everywhere else, combo graphs included.
​
'pill' | 'direct' | 'auto'
default:"auto"
How groups are labeled:
  • 'pill' — a boxed legend with a swatch and label per group.
  • 'direct' — labels drawn next to each group’s endpoint, with no legend box. Reads well on line charts.
  • 'auto' — 'direct' where the graph can anchor direct labels, 'pill' otherwise.
Direct labels need the legend on the right and a single layer on an unflipped cartesian graph: a line, an area, or bars with position: 'stack' or 'fill'. Anywhere else 'direct' falls back to 'pill'.
​
'auto' | 'start' | 'center' | 'end'
default:"auto"
Placement of the items along the legend’s flow:
  • A horizontal (top/bottom) legend runs along the row: start is left and end is right, on right-to-left pages too. center centers on the panel, in line with the axis title.
  • A vertical (left/right) legend runs down the column: start is top, end is bottom.
  • 'auto' resolves to start for horizontal legends and center for vertical ones.
Across the flow, a vertical legend always sits against the plot border.

​
Direct labels

Pin the legend to the right and ask for direct labels:
The labels sit on the plot. style.directLabel paints them, not the legend targets.

​
Continuous color

A color scale that runs a ramp rather than a set of hues gets a legend of its own, one pill per domain stop: the low and high ends, plus the midpoint of a diverging ramp, each in the color the ramp gives that value. It never merges with another aesthetic’s legend and counts as one item for 'auto' placement. position, align and 'none' steer it like any other legend.

​
Headline numbers and the legend

A per-group headline names the same groups as a pill legend, so it takes the legend’s place. Direct labels stay.

​
Hiding the legend

​
Related

  • Mappings & aesthetics — color and group create groups
  • Scales — the color scale that assigns groups their swatches, and the ramps behind a color bar
  • Layout — style.legend margin around a pill legend. Position stays on config.legend.