A Legend aids in matching visual elements in the chart to their corresponding series or data categories.
A Legend is made up of multiple 'items', each of which consists of a 'marker' and a 'label'.
By default, a Legend is displayed below all charts containing more than one series. This can be changed by using the legend.enabled
property.
Layout Copy Link
The Legend is placed below the series area by default. Use the position
property to change this.
Placement Copy Link
The position
property accepts either a string specifying one of the nine preset positions, or an object for more control including Floating, and Offsets.
legend: {
position: 'bottom', // 'top', 'right', 'left', 'top-right', 'right-top' ...
}
legend: {
position: {
placement: 'bottom', // 'top', 'right', 'left', 'top-right', 'right-top' ...,
//other floating or offset options
},
}
Notice that when you change the legend position in the example above:
- The size and position of the Series Area changes to accommodate the Legend within the container.
- The default
orientation
of the Legend changes.- A
vertical
orientation - with the items arranged in columns - when the Legend is positioned to the sides. - A
horizontal
orientation - with the items arranged in rows - when the Legend is positioned to above or below.
- A
Floating Copy Link
By default, the Legend occupies space next to the Series Area and affects the chart Layout.
The Legend can be drawn above the Series Area using the floating: true
property. This will display the Legend above the data and all other chart elements.
legend: {
position: {
placement: 'right-top', // start at the right-top
floating: true, // place the legend above the series area
xOffset: -50, // move the legend 50 pixels left
yOffset: 75, //move the legend 75 pixels down
},
}
Offset and Spacing Copy Link
It is possible to manually offset the position of the Legend, as well as controlling the spacing between the Legend and Series Area.
legend: {
spacing: 20,
position: {
placement: "right",
xOffset: 0,
yOffset: 0,
},
},
In this example:
- The
xOffset
andyOffset
values move the Legend relative to its original position. This does not affect the overall size of the Series Area. - The
spacing
value adjusts the spacing between the Series Area and Legend, and shrinks the Series Area.- Note that the
spacing
option will have no effect iffloating: true
.
- Note that the
Size Copy Link
By default, the overall width and height of the Legend will be a percentage of the chart's width and height.
The Legend width and height can be constrained using the legend.maxWidth
and legend.maxHeight
properties. The Legend will always contain at least one row or column of items.
Padding Copy Link
It is possible to add padding between and within the Legend items.
legend: {
item: {
maxWidth: 130,
paddingX: 32,
paddingY: 8,
marker: {
padding: 8,
}
}
}
Series Stroke Copy Link
The Legend item includes a line, representing the stroke style of the series. Use showSeriesStroke
to disable this.
legend: {
item: {
showSeriesStroke: false,
},
}
In this configuration:
- The stroke styling of the series is shown as a line in the Legend item.
- Legend item markers are only shown if the series has markers enabled.
Pagination Copy Link
If the Legend items don't fit within the size constraints, the items are paginated and the pagination component is displayed.
In this example legend.maxWidth
and legend.maxHeight
are used to constrain the size of the Legend and force pagination.
Use legend.pagination
to customise the styling of the pagination label and buttons. See the API Reference for more details.
Customisation Copy Link
Labels Copy Link
It is possible to customise the label style using the legend.item.label
options, and the displayed text by using legend.item.label.formatter
function.
See the API Reference and Fills & Borders for more details.
Markers Copy Link
The look of the Legend markers is based on the styling of the series that they represent. It is possible to override this behaviour and set the size
, stroke
and shape
of the legend.item.marker
.
legend: {
item: {
marker: {
size: 20,
strokeWidth: 3,
shape: 'diamond', // 'circle', 'square', 'cross', 'plus', 'triangle'
},
},
}
Line Copy Link
The look of the Legend item lines is based on the styling of the series that they represent. It is possible to override this behaviour and set the strokeWidth
and length
of the legend.item.line
.
legend: {
item: {
line: {
strokeWidth: 4,
length: 40, //20 for the marker and 10 on each side
},
},
}
Series Visibility Toggling Copy Link
By default, when a Legend item is clicked, the visibility of the series associated with that item will be toggled. This allows the users to control which series are displayed in the chart by clicking on Legend items.
Additionally, when a Legend item is double clicked, the chart will show that series only. Double clicking again will show all of the series.
In the above example:
- Clicking or double clicking a Legend item will toggle the series visibility.
- It will also log a message to the console via a
legendItemClick
event.
Pie series sectors do not toggle when a Legend item is double clicked.
To disable series toggling on Legend item click or double click, set the legend.toggleSeries
property to false
.
legend: {
toggleSeries: false,
}
To prevent the last visible series from being hidden, use the preventHidingAll
option.
legend: {
preventHidingAll: true,
}
Legend Events Copy Link
The legendItemClick
and legendItemDoubleClick
events can be used to listen to Legend item clicks and double clicks, respectively. They can also be used to call a preventDefault
function for complete control of when to stop the series toggling. For more information see Legend Events.
The seriesVisibilityChange
events can be used to listen for Series Visibility toggling. For more information see Chart Events.