Legends

Jeffrey Heer edited this page Mar 7, 2017 · 8 revisions

This wiki documents Vega version 2. For Vega 3 documentation, see vega.github.io/vega.

WikiDocumentationLegends

Similar to axes, legends visualize scales. However, whereas axes aid interpretation of scales with spatial ranges, legends aid interpretation of scales with ranges such as colors, shapes and sizes. Similar to scales and axes, legends can be defined either at the top-level visualization, or as part of a group mark.

Legends take one or more scales as their primary input. At least one of the size, shape, fill or stroke parameters must be specified. If multiple scales are provided, it is very important that they share the same domain of input vales. Otherwise, the behavior of the legend may be unpredictable.

Legend Properties

Property Type Description
size String The name of the scale that determines an item's size.
shape String The name of the scale that determines an item's shape.
fill String The name of the scale that determines an item's fill color.
stroke String The name of the scale that determines an item's stroke color.
opacity String The name of the scale that determines an item's opacity.
orient String The orientation of the legend. One of "left" or "right". This determines how the legend is positioned within the scene. The default is "right".
offset Number The horizontal offset, in pixels, by which to displace the legend from the edge of the enclosing group or data rectangle.
title String The title for the legend (none by default).
format String An optional formatting pattern for legend labels. Vega uses D3's format pattern.
values Array Explicitly set the visible legend values.
properties Object Optional mark property definitions for custom legend styling. The input object can include sub-objects for title, labels, symbols (for discrete legend items), gradient (for a continuous color gradient) and legend (for the overall legend group). These mark property definitions can make value references to their scale domain data via data property like so: {field: "data"}. This is a shorthand for {field: {datum: "data"}}. The template follows suite: {template: "datum.data"}.

Custom Legend Styles

Custom mark properties can be set for all legend elements through the legend properties setting. The addressable elements are the title, labels, symbols (for discrete legend items), gradient (for a continuous color gradient) and legend (for the overall legend group). Each element can be styled using standard Vega Value References, as described in the Marks documentation.

The following example shows how to set custom fonts and a border on a legend for a fill color encoding.

"legends": [
   {
     "fill": "color",
     "properties": {
       "title": {
         "fontSize": {"value": 14}
       },
       "labels": {
         "fontSize": {"value": 12}
       },
       "symbols": {
         "stroke": {"value": "transparent"}
       },
       "legend": {
         "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 axis values to axis label text.

In addition, one can set the "x" and "y" properties for the legend to perform custom positioning, overriding automatic legend positioning.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.