Legend

Edit this page

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

By default, Vega-Lite automatically creates legends with default properties for color, opacity, size, and shape channels when they encode data fields. User can set the legend property of a mark property channel’s field definition to an object to customize legend properties or set legend to null to remove the legend.

Besides legend property of a field definition, the configuration object (config) also provides legend config (config: {legend: {...}}) for setting default legend properties for all legends.

Legend Types
Combined Legend
Legend Properties
Legend Config
- General
- Gradient
- Labels
- Symbols
- Title

Legend Types

By default, Vega-Lite automatically generates gradient legends for color channels with non-binned quantitative fields and temporal fields.

Otherwise, symbol legends are generated.

Combined Legend

If multiple channels encode the same fields, Vega-lite automatically combines their legends. For example, the following plot uses both color and shape to encode Origin; as a result, its legend shows the encoded colors and shapes.

Legend Properties

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

To customize legends, a legend object in an encoding channel’s definition can contain the following properties:

Property	Type	Description
type	String	The type of the legend. Use `"symbol"` to create a discrete legend and `"gradient"` for a continuous color gradient. Default value: `"gradient"` for non-binned quantitative fields and temporal fields; `"symbol"` otherwise.
entryPadding	Number	Padding (in pixels) between legend entries in a symbol legend.
format	String	The formatting pattern for labels. This is D3’s number format pattern for quantitative fields and D3’s time format pattern for time field. See the format documentation for more information. Default value: derived from numberFormat config for quantitative fields and from timeFormat config for temporal fields.
offset	Number	The offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle. Default value: `0`
orient	String	The orientation of the legend, which determines how the legend is positioned within the scene. One of “left”, “right”, “top-left”, “top-right”, “bottom-left”, “bottom-right”, “none”. Default value: `"right"`
padding	Number	The padding, in pixels, between the legend and axis.
tickCount	Number	The desired number of tick values for quantitative legends.
title	String \| Null	A title for the field. If `null`, the title will be removed. Default value: derived from the field’s name and transformation function (`aggregate`, `bin` and `timeUnit`). If the field has an aggregate function, the function is displayed as part of the title (e.g., `"Sum of Profit"`). If the field is binned or has a time unit applied, the applied function is shown in parentheses (e.g., `"Profit (binned)"`, `"Transaction Date (year-month)"`). Otherwise, the title is simply the field name. Notes: 1) You can customize the default field title format by providing the [`fieldTitle` property in the config or `fieldTitle` function via the `compile` function’s options. 2) If both field definition’s `title` and axis, header, or legend `title` are defined, axis/header/legend title will be used.
values	Number[] \| String[] \| Boolean[] \| DateTime[]	Explicitly set the visible legend values.
zindex	Number	A non-positive integer indicating z-index of the legend. If zindex is 0, legend should be drawn behind all chart elements. To put them in front, use zindex = 1.

Legend Config

// Top-level View Specification
{
  ...
  "config": {
    "legend": {
      ...
    }
  }
}

To provide themes for all legends, the legends config (config: {legend: {...}}) can contain the following properties:

General

Property	Type	Description
cornerRadius	Number	Corner radius for the full legend.
fillColor	String	Background fill color for the full legend.
orient	String	The orientation of the legend, which determines how the legend is positioned within the scene. One of “left”, “right”, “top-left”, “top-right”, “bottom-left”, “bottom-right”, “none”. Default value: `"right"`
offset	Number	The offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle. Default value: `0`
strokeColor	String	Border stroke color for the full legend.
strokeDash	Number[]	Border stroke dash pattern for the full legend.
strokeWidth	Number	Border stroke width for the full legend.
padding	Number	The padding, in pixels, between the legend and axis.

Gradient

Property	Type	Description
gradientLabelBaseline	String	Text baseline for color ramp gradient labels.
gradientLabelLimit	Number	The maximum allowed length in pixels of color ramp gradient labels.
gradientLabelOffset	Number	Vertical offset in pixels for color ramp gradient labels.
gradientStrokeColor	String	The color of the gradient stroke, can be in hex color code or regular color name.
gradientStrokeWidth	Number	The width of the gradient stroke, in pixels.
gradientHeight	Number	The height of the gradient, in pixels.
gradientWidth	Number	The width of the gradient, in pixels.

Labels

Property	Type	Description
labelAlign	String	The alignment of the legend label, can be left, middle or right.
labelBaseline	String	The position of the baseline of legend label, can be top, middle or bottom.
labelColor	String	The color of the legend label, can be in hex color code or regular color name.
labelFont	String	The font of the legend label.
labelFontSize	Number	The font size of legend label. Default value: `10`.
labelLimit	Number	Maximum allowed pixel width of axis tick labels.
labelOffset	Number	The offset of the legend label.
shortTimeLabels	Boolean	Whether month names and weekday names should be abbreviated. Default value: `false`

Symbols

Property	Type	Description
entryPadding	Number	Padding (in pixels) between legend entries in a symbol legend.
symbolColor	String	The color of the legend symbol,
symbolType	String	Default shape type (such as “circle”) for legend symbols.
symbolSize	Number	The size of the legend symbol, in pixels.
symbolStrokeWidth	Number	The width of the symbol’s stroke.

Title

Property	Type	Description
titleAlign	String	Horizontal text alignment for legend titles.
titleBaseline	String	Vertical text baseline for legend titles.
titleColor	String	The color of the legend title, can be in hex color code or regular color name.
titleFont	String	The font of the legend title.
titleFontSize	Number	The font size of the legend title.
titleFontWeight	String	The font weight of the legend title. This can be either a string (e.g `"bold"`, `"normal"`) or a number (`100`, `200`, `300`, …, `900` where `"normal"` = `400` and `"bold"` = `700`).
titleLimit	Number	Maximum allowed pixel width of axis titles.
titlePadding	Number	The padding, in pixels, between title and legend.