Legend

Similar to axes, legends visualize scales. However, whereas axes aid interpretation of scales with spatial ranges, legends aid interpretation of scales with ranges such as colors, shapes and sizes.

By default, Vega-Lite automatically creates legends for color, size, and shape channels when they are encoded. Legend can be further customized via the channel definition’s legend property.

{
  "data": ... ,
  "mark": ... ,
  "encoding": {
    "x": ...,
    "y": ...,
    "color": {
      "field": ...,
      "type": ...,
      "legend": {                // legend
        ...
      },
      ...
    },
    ...
  },
  ...
}

Customizing Legend

The field’s legend can be removed by setting legend to false. If legend is true, default legend properties are applied.

Legend properties can be overridden by setting legend to a legend property object. The legend property object supports the following properties:

General

Property	Type	Description
orient	String	The orientation of the legend. One of `"left"` or `"right"`. This determines how the legend is positioned within the scene. Default value: derived from legend config’s `orient` (`"right"` by default).
offset	Number	The offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle. Default value: derived from legend config’s `offset` (`0` by default).
values	Array \| DateTime[]	Explicitly set the visible legend values.

Labels

Property	Type	Description
format	String	The formatting pattern for legend labels. This is D3’s number format pattern for quantitative axis and D3’s time format pattern for time axis. Default value: derived from `numberFormat` config for quantitative axis and from `timeFormat` config for time axis..
labelAlign	String	The alignment of the legend label. One of `"left"`, `"right"` or `"center"`.
labelBaseline	String	The position of the baseline of legend label. One of `"top"`, `"middle"` or `"bottom"`.
labelColor	String	The color of the legend label.
labelFont	String	The font of the label (e.g., `Helvetica Neue`).
labelFontSize	Number	The font size of the label, in pixels. Default value: 10.
shortTimeLabels	Boolean	Whether month and day names should be abbreviated. Default value: derived from legend config’s `shortTimeLabels` (`false` by default).

Symbols

Property	Type	Description
symbolColor	String	The color of the symbol.
symbolShape	String	The shape of the legend symbol. One of `"circle"`, `"square"`, `"cross"`, `"diamond"`, `"triangle-up"`, `"triangle-down"`, or else a custom SVG path string
symbolSize	Number	The size of the symbol, in pixels.
symbolStrokeWidth	Number	The width of the symbol’s stroke.

Title

Property	Type	Description
title	String	The title for the legend. Default value: derived from the field’s name and transformation function applied e.g, “field_name”, “SUM(field_name)”, “BIN(field_name)”, “YEAR(field_name)”.
titleColor	String	The color of the title.
titleFont	String	The font of the title (e.g., `Helvetica Neue`).
titleFontSize	Number	The font size of the title.
titleFontWeight	String	The font weight of the title (e.g., `bold`).