Legends

Legends visualize scale mappings for visual values such as color, shape and size. Similar to scales and axes, legends can be defined either at the top-level visualization, or within the scope of a group mark.

Legend Properties

Properties for specifying a legend. Legends accept one or more scales as parameters. At least one of the size, shape, fill, stroke, strokeDash, or opacity properties must be specified. If multiple scales are provided, they must share the same domain of input vales. Otherwise, the behavior of the legend is undefined.

Property Type Description
type String The type of legend to include. One of symbol for discrete symbol legends, or gradient for a continuous color gradient. If gradient is used only the fill or stroke scale parameters are considered. If unspecified, the type will be inferred based on the scale parameters used and their backing scale types.
direction String The direction of the legend, one of "vertical" (default) or "horizontal".
orient String The orientation of the legend, determining where the legend is placed relative to a chart’s data rectangle (default right). See the legend orientation reference.
fill String The name of a scale that maps to a fill color.
opacity String The name of a scale that maps to an opacity value.
shape String The name of a scale that maps to a shape value.
size String The name of a scale that maps to a size (area) value.
stroke String The name of a scale that maps to a stroke color.
strokeDash String The name of a scale that maps to a stroke dash value.
strokeWidth String The name of a scale that maps to a stroke width value. ≥ 5.0
encode Object Optional mark encodings for custom legend styling. Supports encoding blocks for legend, title, entries, labels, symbols and gradient. See custom legend encodings.
format String | TimeMultiFormat The format specifier pattern for legend labels. For numerical values, must be a legal d3-format specifier. For date-time values, must be a legal d3-time-format specifier or a TimeMultiFormat object.
formatType String Specifies the type of format to use ("number", "time", "utc") for scales that do not have a strict domain data type. This property is useful for formatting date-time values for ordinal scales. If specified, the format property must have a valid specifier pattern for the given type. Supported ≥ 5.1, UTC support ≥ 5.8.
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.
clipHeight Number The height in pixels to clip symbol legend entries and limit their size. By default no clipping is performed.
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. The default is 0 for horizontal symbol legends and 1 for vertical symbol legends.
columnPadding Number The horizontal padding in pixels between symbol legend entries.
rowPadding Number The vertical padding in pixels between symbol legend entries.
cornerRadius Number Corner radius for the full legend.
fillColor Color Background fill color for the full legend.
offset Number | Value The offset in pixels by which to displace the legend from the data rectangle and axes. If provided, this value will override any values specified in the legend config. If multiple offset values are specified for a collection of legends with the same orient value, the maximum offset will be used.
padding Number | Value The padding between the border and content of the legend group.
strokeColor Color Border stroke color for the full legend.
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.
gradientOpacity Number Opacity of the color gradient. ≥ 4.1
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.
gradientStrokeColor Color Stroke color of the color gradient border.
gradientStrokeWidth Number Stroke width of the color gradient border.
labelAlign String Horizontal text alignment for legend labels.
labelBaseline String Vertical text baseline for legend labels. One of alphabetic (default), top, middle, bottom, line-top, or line-bottom. The line-top and line-bottom values ≥ 5.10 operate similarly to top and bottom, but are calculated relative to the lineHeight rather than fontSize alone.
labelColor Color Text color for legend labels.
labelFont String Font name for legend labels.
labelFontSize Number Font size in pixels for legend labels.
labelFontStyle String Font style of legend labels (e.g., normal or italic). ≥ 5.0
labelFontWeight String | Number Font weight of legend labels.
labelLimit Number The maximum allowed length in pixels of legend labels.
labelOffset Number Offset in pixels between legend labels their corresponding symbol or gradient.
labelOpacity Number Opacity of legend labels. ≥ 4.1
labelOverlap Boolean | 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.
labelSeparation Number The minimum separation that must be between label bounding boxes for them to be considered non-overlapping (default 0). This property is ignored if labelOverlap resolution is not enabled. ≥ 5.0
legendX Number The pixel x-coordinate of the legend group. Only applied if the orient value is "none". ≥ 5.4
legendY Number The pixel y-coordinate of the legend group. Only applied if the orient value is "none". ≥ 5.4
symbolDash Number[ ] Stroke dash of symbol outlines (or [] for solid lines). ≥ 5.0
symbolDashOffset Number The pixel offset at which to start the symbol dash array. ≥ 5.0
symbolFillColor Color Fill color for legend symbols.
symbolLimit Number The maximum number of allowed entries for a symbol legend. If the number of entries exceeds the limit, entries will be dropped and replaced with an ellipsis. ≥ 5.7
symbolOffset Number Horizontal pixel offset for legend symbols.
symbolOpacity Number Opacity of legend symbols. ≥ 4.1
symbolSize Number Default symbol area size (in pixels2).
symbolStrokeColor Color Stroke color for legend symbols.
symbolStrokeWidth Number Default legend symbol stroke width.
symbolType String Default symbol mark shape type (such as "circle") for legend symbols.
tickCount Number | String | Object The desired number of tick values for quantitative legends. For scales of type time or utc, the tick count can instead be a time interval specifier. Legal string values are "millisecond", "second", "minute", "hour", "day", "week", "month", and "year". Alternatively, an object-valued interval specifier of the form {"interval": "month", "step": 3} includes a desired number of interval steps. Here, ticks are generated for each quarter (Jan, Apr, Jul, Oct) boundary.
tickMinStep Number The minimum desired step between tick values for quantitative legends, in terms of scale domain values. For example, a value of 1 indicates that ticks should not be less than 1 unit apart. If tickMinStep is specified, the tickCount value will be adjusted, if necessary, to enforce the minimum step value. ≥ 5.0
title String | String[ ] The title for the legend (none by default). For versions ≥ 5.7, a string array specifies a title with multiple lines of text.
titleAnchor String The anchor position for placing the legend title. One of "start", "middle", "end", or null (default, for automatic determination). For example, with a titleOrient of "top" these anchor positions map to a left-, center-, or right-aligned title relative to the legend contents. ≥ 5.0
titleAlign String Horizontal text alignment of the legend title. One of "left", "center", or "right". If specified, this value overrides automatic alignment based on the titleOrient and titleAnchor values.
titleBaseline String Vertical text baseline of the legend title. One of alphabetic (default), top, middle, bottom, line-top, or line-bottom. The line-top and line-bottom values ≥ 5.10 operate similarly to top and bottom, but are calculated relative to the lineHeight rather than fontSize alone. If specified, this value overrides the automatic baseline based on the titleOrient and titleAnchor values.
titleColor Color Text color of the legend title.
titleFont String Font name of the legend title.
titleFontSize Number Font size in pixels of the legend title.
titleFontStyle String Font style of the legend title (e.g., normal or italic). ≥ 5.0
titleFontWeight String | Number Font weight of the legend title.
titleLimit Number The maximum allowed length in pixels of the legend title.
titleLineHeight Number Line height in pixels for multi-line title text or title text with "line-top" or "line-bottom" baseline. ≥ 5.7
titleOpacity Number Opacity of the legend title. ≥ 4.1
titleOrient String The orientation of the title legend, determining where it is placed relative to the legend contents. One of "top" (default), "left", "bottom", or "right". ≥ 5.0
titlePadding Number | Value The padding between the legend title and entries.
values Array Explicitly set the visible legend values. The array entries should be legal values in the backing scale domain.
zindex Number The integer z-index indicating the layering of the legend group relative to other axis, mark, and legend groups. The default value is 0.

Accessibility Properties ≥ 5.11

Accessibility properties are used to determine ARIA (Accessible Rich Internet Applications) attributes when using Vega to render SVG output.

Property Type Description
aria Boolean A boolean flag (default true) 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.
description String 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.

Themes and Configuration

To create themes, new default values for legend properties can be set using a config object. The config object also supports customized layout behavior for collections of legends with the same orient value.

Legend Orientation Reference

Valid settings for the legend orient parameter.

Value Description
left Place the legend to the left of the chart.
right Place the legend to the right of the chart.
top Place the legend above the top of the chart.
bottom Place the legend below the bottom of the chart.
top-left Place the legend inside the upper left corner of the chart.
top-right Place the legend inside the upper right corner of the chart.
bottom-left Place the legend inside the lower left corner of the chart.
bottom-right Place the legend inside the lower right corner of the chart.
none Do not perform automatic layout. Allows custom layout by setting the legendX and legendY properties of the legend.

Multiple legends: If multiple legends have a left or right orientation, they will be vertically ordered by default. If multiple legends have a top or bottom orientation, they will be horizontally ordered by default. In all other cases, legends will be drawn on top of each other when placed in the same location. The multiple legend layout can be customized by setting the legend layout config.

Legend offset: In the case of left, right, top and bottom orientation, the offset parameter determines how far away the legend is placed from the rest of the chart. If the orientation is none, the offset parameter is ignored. For all other settings, the offset determines the distance the legend is moved inward from a corner of the data rectangle.

Custom Legend Encodings

Custom mark properties can be set for all legend elements using the encode parameter. The addressable elements are:

  • legend for the legend group mark,
  • title for the title text mark,
  • labels for label text marks,
  • symbols for legend symbol marks,
  • entries for symbol legend group marks containing a symbol / label pair, and
  • gradient for a gradient rect marks: one rect with gradient fill for continuous gradient legends, multiple rect marks with solid fill for discrete gradient legends.

Each element accepts a set of visual encoding directives grouped into enter, update, exit, etc. objects as described in the Marks documentation. Mark properties can be styled using standard value references.

In addition, each encode block may include a string-valued name property to assign a unique name to the mark set, a boolean-valued interactive property to enable input event handling, and a string-valued (or array-valued) style property to apply default property values. Unless otherwise specified, title elements use a default style of "guide-title" and labels elements use a default style of "guide-label".

Each legend symbol and label instance is backed by a data object with the following fields, which may be accessed as part of a custom visual encoding rule:

  • index - an integer index
  • label - the string label
  • value - the data value
  • size - the symbol size (for symbol legends only)

The following example shows how to set custom fonts and a border on a legend for a fill color encoding. The labels encoding block also make legend labels responsive to input events, and changes the text color on mouse hover.

"legends": [
  {
    "fill": "color",
    "encode": {
      "title": {
        "update": {
          "fontSize": {"value": 14}
        }
      },
      "labels": {
        "interactive": true,
        "update": {
          "fontSize": {"value": 12},
          "fill": {"value": "black"}
        },
        "hover": {
          "fill": {"value": "firebrick"}
        }
      },
      "symbols": {
        "update": {
          "stroke": {"value": "transparent"}
        }
      },
      "legend": {
        "update": {
          "stroke": {"value": "#ccc"},
          "strokeWidth": {"value": 1.5}
        }
      }
    }
  }
]

Custom text can be defined using the text property for labels. For example, one could define an ordinal scale that serves as a lookup table from a backing value to legend label text. Note: to perform custom positioning when orient is none, use the top-level legendX and legendY properties, do not use x and y properties within a custom encoding block.