This website is for Vega-Lite v3. Go to the main Vega-Lite homepage for the latest release.

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
cornerRadius Number

Corner radius for the full legend.
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 Color

Background fill color for the full legend.
legendX Number

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

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

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

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

Default value: 0.
strokeColor Color

Border stroke color for the full legend.
strokeWidth Any
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 Number

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

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

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.
gradientThickness Number

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.
gradientStrokeColor Color

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

Default value: "lightGray".
gradientStrokeWidth Number

The width of the gradient stroke, in pixels.

Default value: 0.

Labels

Property Type Description
format String

The text formatting pattern for labels of guides (axes, legends, headers) and text marks.

See the format documentation for more examples.

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

The format type for labels ("number" or "time").

Default value:

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

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

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

Default value: "middle".
labelColor Color

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.
labelFontStyle FontStyle

The font style of legend label.
labelLimit Number

Maximum allowed pixel width of legend tick labels.

Default value: 160.
labelOffset Number

The offset of the legend label.
labelOverlap String

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
symbolFillColor Color

The color of the legend symbol,
symbolSize Number

The size of the legend symbol, in pixels.

Default value: 100.
symbolStrokeColor Color

Stroke color for legend symbols.
symbolStrokeWidth Number

The width of the symbol’s stroke.

Default value: 1.5.
symbolType String

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

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

The horizontal padding in pixels between symbol legend entries.

Default value: 10.
columns Number

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

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

The vertical padding in pixels between symbol legend entries.

Default value: 2.

Title

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

Horizontal text alignment for legend titles.

Default value: "left".
titleAnchor TitleAnchor

Text anchor position for placing legend titles.
titleBaseline String

Vertical text baseline for legend titles.

Default value: "top".
titleColor Color

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.
titleFontStyle FontStyle

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

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 legend titles.

Default value: 180.
titleOpacity Number

Opacity of the legend title.
titlePadding Number

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
gradientDirection String

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

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

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 Color

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

Default value: "transparent".
symbolBaseStrokeColor Color

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

Default value: "gray".
symbolDirection String

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

Default value: "vertical".
symbolOffset Number

Horizontal pixel offset for legend symbols.

Default value: 0.
shortTimeLabels Boolean

Whether month names and weekday names should be abbreviated.

Default value: false
strokeDash Number[]

Border stroke dash pattern for the full legend.