React ChartsLegend
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.
A legend is shown by default but can be hidden using the enabled
config:
legend: {
enabled: false
}
When enabled, it can be positioned to any side of a chart using the position
config:
legend: {
position: "right" // 'bottom', 'left', 'top'
}
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
The legend can have a vertical
or horizontal
orientation. The arrangement of legend items can be configured using the legend.orientation
property.
In the vertical
orientation, the legend items are arranged using the minimum number of columns possible given the current dimension constraints.
By default, when the legend is positioned to the 'right'
or 'left'
of a chart, it is rendered in a vertical
orientation.
The number of columns in a vertical
legend increases as the height of a chart shrinks, as fewer legend items can be placed in a given column.
If the legend is horizontal
, the legend items are arranged using the minimum possible number of rows. If the legend is not wide enough, the items are divided into more rows until everything fits.
By default, when the legend is positioned to the 'bottom'
or 'top'
of a chart, it is rendered in a horizontal
orientation. The number of rows in a horizontal
legend increases as the width of a chart shrinks, as fewer legend items can be placed in a given row.
The legend width and height can be constrained using the legend.maxWidth
and legend.maxHeight
properties.
By default, the legend width and height will be a percentage of the chart width and height depending on the legend's orientation.
If the legend maxWidth
or maxHeight
is set to a value which is larger than the chart width
or height
, the legend may overflow the chart and become clipped. Likewise, if the maxWidth
or maxHeight
is too small, the legend layout will contain at least one row or column of items depending on the orientation
.
In addition to maxWidth
and maxHeight
, the legend's layout is also affected by the amount of padding between the legend items. For example, legend.item.paddingX
controls the amount of padding between adjacent horizontal legend items:
legend: {
item: {
paddingX: 16
}
}
legend.item.paddingY
controls the amount of padding between adjacent vertical legend items:
legend: {
item: {
paddingY: 8
}
}
And the legend.item.marker.padding
config is responsible for the amount of padding within a legend item, between the marker and the label:
legend: {
item: {
marker: {
padding: 8
}
}
}
Please refer to the example below to get a better idea of how the above configs affect the legend layout.
If the legend items don't fit within the constraints, the items will be paginated and the pagination component will be displayed.
The pagination component can be customised using legend.pagination
. For example, the pagination button markers can be made larger with legend.pagination.marker
:
legend: {
pagination: {
marker: {
size: 18
}
}
}
legend.pagination.activeStyle
and legend.pagination.inactiveStyle
can be used to style the pagination buttons when in the active and inactive states.
legend: {
pagination: {
activeStyle: {
fill: 'blue',
strokeWidth: 0,
},
inactiveStyle: {
fillOpcacity: 0,
}
}
}
- Initially the legend is positioned at the bottom of the chart so by default, the legend is rendered in the
horizontal
orientation. legend.maxHeight
is used to restrict the height of the legend, resulting in a single row of legend items spread across different pages.- The pagination component appears automatically when the legend items combined with their configured padding do not fit in the given width and height constraints.
legend.pagination
is used to customise the styles of the pagination label and buttons.- You can switch between different legend positions using the buttons above the chart to see how the legend pagination component behaves.
There are a number of configs that affect the fontSize
, fontStyle
, fontWeight
, fontFamily
, and color
of the legend item labels.
maxLength
can also be configured to constrain the length of legend item labels, if the label text exceeds the maximum length, it will be truncated and an ellipsis will be appended.
legend: {
item: {
label: {
fontSize: 14,
fontStyle: 'italic',
fontWeight: 'bold',
fontFamily: 'Papyrus',
color: 'red',
maxLength: 25
}
}
}
All legend items use the same size
and strokeWidth
, regardless of the size
and strokeWidth
used by the series they represent. It's possible to adjust the defaults using the following configs:
legend: {
item: {
marker: {
size: 20,
strokeWidth: 3
}
}
}
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 'square'
.
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:
legend: {
item: {
marker: {
shape: 'circle', // 'square', 'diamond', 'cross', 'plus', 'triangle'
}
}
}
By default, when a legend item is clicked, the visibility of the series associated with that legend 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, it will make only that series visible.
To disable series toggling on legend item click or double click, the legend.item.toggleSeriesVisible
property can be set to false
:
legend: {
item: {
toggleSeriesVisible: false
}
}
If a callback function is configured via legend.listeners.legendItemClick
, it will still be invoked when the legend click event is fired.
The legendItemClick
and legendItemDoubleClick
events can be used to listen to legend item clicks and double clicks, respectively. For more information see Legend Events.
This example demonstrates toggling the visiblity of series via clicks and double clicks, and logs a message to the browser console when the legend is clicked.
Properties available on the AgChartLegendOptions
interface.