Skip to main content
The legend section controls where the legend sits and how it presents series. A legend appears automatically when a chart maps color (or group) to more than one series.

​
Options

​
'auto' | 'top' | 'bottom' | 'left' | 'right' | 'none'
default:"auto"
Where the legend sits. 'none' hides it; 'auto' lets the engine choose based on the chart.
​
'pill' | 'direct' | 'auto'
default:"auto"
How series are labelled:
  • 'pill' — a boxed legend with a swatch and label per series.
  • 'direct' — labels drawn next to each series’ endpoint, no separate legend box. Reads well on line charts.
  • 'auto' — resolved during compilation from the chart type and legend position.
​
'auto' | 'start' | 'center' | 'end'
default:"auto"
Placement of the legend items along the legend’s flow:
  • For a horizontal (top/bottom) legend this runs along the row — start is left, end is right.
  • For a vertical (left/right) legend it 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 pins to the plot border.

​
Direct labels

Combine display: 'direct' with position to steer which side the labels flow toward:

​
Continuous color

A color scale that runs a ramp rather than a set of hues draws a gradient colour bar instead of a row of swatches — sampled across the scale’s domain, so a diverging ramp shows where its neutral point falls. position, align and 'none' steer it like any other legend; display: 'direct' doesn’t apply, since there are no series to label.

​
Hiding the legend

​
Related

  • Mappings & aesthetics — color and group create series
  • Scales — the color scale that assigns series their swatches, and the ramps behind a colour bar