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

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 a part of the title (e.g., "Sum of Profit"). If the field is binned or has a time unit applied, the applied function will be denoted in parentheses (e.g., "Profit (binned)", "Transaction Date (year-month)"). Otherwise, the title is simply the field name.

Note: 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.

values Number[] | String[] | 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 | Number

The font weight of the legend title.

titleLimit Number

Maximum allowed pixel width of axis titles.

titlePadding Number

The padding, in pixels, between title and legend.