Framework:Javascript GridAngular GridReact GridVue Grid

Vue Charts: Legend

A legend makes it easier to tell at a glance which series or series items correspond to which pieces of data. This section describes the legend options and layout behaviour.

Position and Visibility

A legend can be positioned to any side of a chart using the position config:

legend: {
    position: 'right' // 'bottom', 'left', 'top'
}

A legend is shown by default but can be hidden using the enabled config:

legend: {
    enabled: false
}

Example: Legend Position and Visibility

Notice how when you click on one of the buttons in the example to change the position of the legend:

  • the layout of the legend items also changes
  • the layout of the chart changes as well, with series moving around and growing/shrinking slightly to accommodate the legend

Vertical Layout

Whenever the size of a chart changes, the legend layout is triggered. If the legend is vertical (positioned to the 'right' or 'left' of a chart), the layout algorithm tries to use the minimum number of columns possible to render all legend items using current constraints. Notice how the number of columns in a legend increases as the height of a chart shrinks.

Example: Vertical Legend Layout

Horizontal Layout

If the legend is horizontal (positioned to the 'bottom' or 'top' of a chart), the layout algorithm tries to use the minimum possible number of rows. If a chart is not wide enough, the legend will keep subdividing its items into more rows until everything fits.

Example: Horizontal Legend Layout

Constraints

In addition to the width and height of the chart, the legend's layout is also affected by the amount of spacing between and within the legend items. For example, layoutHorizontalSpacing controls the amount of spacing between adjacent horizontal legend items:

legend: {
    layoutHorizontalSpacing: 16
}

layoutVerticalSpacing controls the amount of spacing between adjacent vertical legend items:

legend: {
    layoutVerticalSpacing: 8
}

And the itemSpacing config is responsible for the amount of spacing within a legend item, between the marker and the label:

legend: {
    itemSpacing: 8
}

Example: Legend Constraints

Fonts

There are a number of configs that affect the fontSize, fontStyle, fontWeight, fontFamily, and color of the legend item labels:

legend: {
    fontSize: 14,
    fontStyle: 'italic',
    fontWeight: 'bold',
    fontFamily: 'Papyrus',
    color: 'red'
}

Markers

Size and Stroke

All legend items use the same size and stroke width, regardless of the size and stroke width used by the series they represent. It's possible to adjust the defaults using the following configs:

legend: {
    markerSize: 20,
    strokeWidth: 3
}

Shape

Normally, the legend mirrors the marker shapes used by the series, unless the series in question doesn't support markers (for example 'column' series), in which case the legend will use the 'square' marker shape for that series.

It's also possible to override the default behaviour and make the legend use a specified marker shape for all legend items, regardless of the shapes the series are using themselves:

legend: {
    markerShape: 'circle' // 'square', 'diamond', 'cross', 'plus', 'triangle'
}

API Reference

enabled
boolean
Whether or not to show the legend.
Default: true
position
string
Where the legend should show in relation to the chart.
Default: 'right'
Options: 'top', 'right', 'bottom', 'left'
spacing
number
The spacing in pixels to use outside the legend.
Default: 20
item
Configuration for the legend items that consist of a marker and a label.
See item for more details.

item

legend > item

Configuration for the legend items that consist of a marker and a label.

legend: {
  ...
  item: {
    paddingX?: number; // default: 16
    paddingY?: number; // default: 8
    marker?: Marker;
    label?: Label;
  }
}
paddingX
number
The horizontal spacing in pixels to use between legend items.
Default: 16
paddingY
number
The vertical spacing in pixels to use between legend items.
Default: 8
marker
Configuration for the legend markers.
See marker for more details.
label
Configuration for the legend labels.
See label for more details.

marker

legend > item > marker

Configuration for the legend markers.

legend: {
  ...
  item: {
    ...
    marker: {
      padding?: number; // default: 8
      shape?: string;
      size?: number; // default: 15
      strokeWidth?: number; // default: 1
    }
  }
}
padding
number
The padding in pixels between a legend marker and the corresponding label.
Default: 8
shape
string
If set, overrides the marker shape from the series and the legend will show the specified marker shape instead. If not set, will use a marker shape matching the shape from the series, or fall back to 'square' if there is none.
Options: 'circle', 'cross', 'diamond', 'plus', 'square', 'triangle'
size
number
The size in pixels of the markers in the legend.
Default: 15
strokeWidth
number
The width in pixels of the stroke for markers in the legend.
Default: 1

label

legend > item > label

Configuration for the legend labels.

legend: {
  ...
  item: {
    ...
    label: {
      color?: string; // default: 'black'
      fontStyle?: 'normal' | 'italic' | 'oblique'; // default: 'normal'
      fontWeight?: 'normal' | 'bold' | 'bolder' | 'lighter' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'; // default: 'normal'
      fontSize?: number; // default: 12
      fontFamily?: string; // default: 'Verdana, sans-serif'
      formatter?: Function;
    }
  }
}
color
string
The colour of the text.
Default: 'black'
fontStyle
string
The font style to use for the legend.
Default: 'normal'
Options: 'normal', 'italic', 'oblique'
fontWeight
string
The font weight to use for the legend.
Default: 'normal'
Options: 'normal', 'bold', 'bolder', 'lighter', '100', '200', '300', '400', '500', '600', '700', '800', '900'
fontSize
number
The font size in pixels to use for the legend.
Default: 12
fontFamily
string
The font family to use for the legend.
Default: 'Verdana, sans-serif'
formatter
Function
Function used to render legend labels. Where id is a series ID, itemId is component ID within a series, such as a field name or an item index.
formatter = (params: FormatterParams) => string;

interface FormatterParams {
  id: string;
  itemId: any;
  value: string;
}

Next Up

Continue to the next section to learn more about the navigator.