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.

Accessibility Properties ≥ 5.11

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

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.

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.