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

// A Single View or a Layer Specification
{
  ...,
  "mark/layer": ...,
  "encoding": {
    "x": ...,
    "y": ...,
    "color": {
      "field": ...,
      "type": ...,
      "legend": {                // legend
        ...
      },
      ...
    },
    ...
  }
}

To customize legends, you can specify a legend object in an encoding channel’s definition. This section lists all properties of legends.

See also: This interactive article demonstrates axes and legends in the underlying Vega language.

General

Property Type Description
aria Boolean | ExprRef

A boolean flag indicating if ARIA attributes should be included (SVG output only). If false, the “aria-hidden” attribute will be set on the output SVG group, removing the legend from the ARIA accessibility tree.

Default value: true
cornerRadius Number | ExprRef

Corner radius for the full legend.
description String | ExprRef

A text description of this legend for ARIA accessibility (SVG output only). If the aria property is true, for SVG output the “aria-label” attribute will be set to this description. If the description is unspecified it will be automatically generated.
direction String

The direction of the legend, one of "vertical" or "horizontal".

Default value:

  • For top-/bottom-oriented legends, "horizontal"
  • For left-/right-oriented legends, "vertical"
  • For top/bottom-left/right-oriented legends, "horizontal" for gradient legends and "vertical" for symbol legends.
fillColor Null | Color | ExprRef

Background fill color for the full legend.
legendX Number | ExprRef

Custom x-position for legend with orient “none”.
legendY Number | ExprRef

Custom y-position for legend with orient “none”.
offset Number | ExprRef

The offset in pixels by which to displace the legend from the data rectangle and axes.

Default value: 18.
orient String

The orientation of the legend, which determines how the legend is positioned within the scene. One of "left", "right", "top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right", "none".

Default value: "right"
padding Number | ExprRef

The padding between the border and content of the legend group.

Default value: 0.
strokeColor Null | Color | ExprRef

Border stroke color for the full legend.
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.
tickCount TickCount | ExprRef

The desired number of tick values for quantitative legends.
values Number[] | String[] | Boolean[] | DateTime[] | ExprRef

Explicitly set the visible legend values.
zindex Number

A non-negative integer indicating the 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.

Gradient

Property Type Description
gradientLength Number | ExprRef

The length in pixels of the primary axis of a color gradient. This value corresponds to the height of a vertical gradient or the width of a horizontal gradient.

Default value: 200.
gradientOpacity Number | ExprRef

Opacity of the color gradient.
gradientStrokeColor Null | Color | ExprRef

The color of the gradient stroke, can be in hex color code or regular color name.

Default value: "lightGray".
gradientStrokeWidth Number | ExprRef

The width of the gradient stroke, in pixels.

Default value: 0.
gradientThickness Number | ExprRef

The thickness in pixels of the color gradient. This value corresponds to the width of a vertical gradient or the height of a horizontal gradient.

Default value: 16.

Labels

Property Type Description
format String | Object

When used with the default "number" and "time" format type, the text formatting pattern for labels of guides (axes, legends, headers) and text marks.

See the format documentation for more examples.

When used with a custom formatType, this value will be passed as format alongside datum.value to the registered function.

Default value: Derived from numberFormat config for number format and from timeFormat config for time format.
formatType String

The format type for labels. One of "number", "time", or a registered custom format type.

Default value:

  • "time" for temporal fields and ordinal and nominal fields with timeUnit.
  • "number" for quantitative fields as well as ordinal and nominal fields without timeUnit.
labelAlign String | ExprRef

The alignment of the legend label, can be left, center, or right.
labelBaseline String | ExprRef

The position of the baseline of legend label, can be "top", "middle", "bottom", or "alphabetic".

Default value: "middle".
labelColor Null | Color | ExprRef

The color of the legend label, can be in hex color code or regular color name.
labelExpr String

Vega expression for customizing labels.

Note: The label text and value can be assessed via the label and value properties of the legend’s backing datum object.
labelFont String | ExprRef

The font of the legend label.
labelFontSize Number | ExprRef

The font size of legend label.

Default value: 10.
labelFontStyle String | ExprRef

The font style of legend label.
labelLimit Number | ExprRef

Maximum allowed pixel width of legend tick labels.

Default value: 160.
labelOffset Number | ExprRef

The offset of the legend label.

Default value: 4.
labelOverlap String | ExprRef

The strategy to use for resolving overlap of labels in gradient legends. If false, no overlap reduction is attempted. If set to true (default) or "parity", a strategy of removing every other label is used. If set to "greedy", a linear scan of the labels is performed, removing any label that overlaps with the last visible label (this often works better for log-scaled axes).

Default value: true.

Symbols

Property Type Description
symbolDash Number[] | ExprRef

An array of alternating [stroke, space] lengths for dashed symbol strokes.
symbolDashOffset Number | ExprRef

The pixel offset at which to start drawing with the symbol stroke dash array.
symbolFillColor Null | Color | ExprRef

The color of the legend symbol,
symbolOffset Number | ExprRef

Horizontal pixel offset for legend symbols.

Default value: 0.
symbolOpacity Number | ExprRef

Opacity of the legend symbols.
symbolSize Number | ExprRef

The size of the legend symbol, in pixels.

Default value: 100.
symbolStrokeColor Null | Color | ExprRef

Stroke color for legend symbols.
symbolStrokeWidth Number | ExprRef

The width of the symbol’s stroke.

Default value: 1.5.
symbolType String | ExprRef

The symbol shape. One of the plotting shapes circle (default), square, cross, diamond, triangle-up, triangle-down, triangle-right, or triangle-left, the line symbol stroke, or one of the centered directional shapes arrow, wedge, or triangle. Alternatively, a custom SVG path string can be provided. For correct sizing, custom shape paths should be defined within a square bounding box with coordinates ranging from -1 to 1 along both the x and y dimensions.

Default value: "circle".

Symbol Layout

Property Type Description
clipHeight Number | ExprRef

The height in pixels to clip symbol legend entries and limit their size.
columnPadding Number | ExprRef

The horizontal padding in pixels between symbol legend entries.

Default value: 10.
columns Number | ExprRef

The number of columns in which to arrange symbol legend entries. A value of 0 or lower indicates a single row with one column per entry.
gridAlign String | ExprRef

The alignment to apply to symbol legends rows and columns. The supported string values are "all", "each" (the default), and none. For more information, see the grid layout documentation.

Default value: "each".
rowPadding Number | ExprRef

The vertical padding in pixels between symbol legend entries.

Default value: 2.
symbolLimit Number | ExprRef

The maximum number of allowed entries for a symbol legend. Additional entries will be dropped.

Title

Property Type Description
title Text | 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.
titleAlign String | ExprRef

Horizontal text alignment for legend titles.

Default value: "left".
titleAnchor Null | String | ExprRef

Text anchor position for placing legend titles.
titleBaseline String | ExprRef

Vertical text baseline for legend titles. One of "alphabetic" (default), "top", "middle", "bottom", "line-top", or "line-bottom". The "line-top" and "line-bottom" values operate similarly to "top" and "bottom", but are calculated relative to the lineHeight rather than fontSize alone.

Default value: "top".
titleColor Null | Color | ExprRef

The color of the legend title, can be in hex color code or regular color name.
titleFont String | ExprRef

The font of the legend title.
titleFontSize Number | ExprRef

The font size of the legend title.
titleFontStyle String | ExprRef

The font style of the legend title.
titleFontWeight String | Number | ExprRef

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 | ExprRef

Maximum allowed pixel width of legend titles.

Default value: 180.
titleLineHeight Number | ExprRef

Line height in pixels for multi-line title text or title text with "line-top" or "line-bottom" baseline.
titleOpacity Number | ExprRef

Opacity of the legend title.
titlePadding Number | ExprRef

The padding, in pixels, between title and legend.

Default value: 5.

Legend Config

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

To provide themes for all legends, the legend config (config: {legend: {...}}) supports all legend properties except direction (there are legend-specific gradientDirection and symbolDirection instead), format, tickCount, values, and zindex.

The legend configuration also supports the following properties:

Property Type Description
disable Boolean

Disable legend by default
gradientDirection String | ExprRef

The default direction ("horizontal" or "vertical") for gradient legends.

Default value: "vertical".
gradientHorizontalMaxLength Number

Max legend length for a horizontal gradient when config.legend.gradientLength is undefined.

Default value: 200
gradientHorizontalMinLength Number

Min legend length for a horizontal gradient when config.legend.gradientLength is undefined.

Default value: 100
gradientLabelLimit Number | ExprRef

The maximum allowed length in pixels of color ramp gradient labels.
gradientLabelOffset Number | ExprRef

Vertical offset in pixels for color ramp gradient labels.

Default value: 2.
gradientVerticalMaxLength Number

Max legend length for a vertical gradient when config.legend.gradientLength is undefined.

Default value: 200
gradientVerticalMinLength Number

Min legend length for a vertical gradient when config.legend.gradientLength is undefined.

Default value: 100
symbolBaseFillColor Null | Color | ExprRef

Default fill color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.

Default value: "transparent".
symbolBaseStrokeColor Null | Color | ExprRef

Default stroke color for legend symbols. Only applied if there is no "fill" scale color encoding for the legend.

Default value: "gray".
symbolDirection String | ExprRef

The default direction ("horizontal" or "vertical") for symbol legends.

Default value: "vertical".
unselectedOpacity Number

The opacity of unselected legend entries.

Default value: 0.35.