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
Position
The default position of a Legend is below the chart. However, this can be changed with the position
property.
legend: {
position: 'bottom', // 'top', 'right', 'left',
}
Notice that when you change the legend position in the example above:
- The size and position of the chart changes to accommodate the Legend within the container.
- The default
orientation
of the Legend changes.- A
vertical
orientation - with the items arranged in columns - is used when the Legend is positioned toright
orleft
. - A
horizontal
orientation - with the items arranged in rows - is used when the Legend is positioned totop
orbottom
.
- A
Size
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
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
It is possible to display a line in the Legend item, representing the stroke style of the series.
legend: {
item: {
showSeriesStroke: true,
},
}
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
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
Labels
It is possible to customise the look of the item label using legend.item.label
.
legend: {
item: {
label: {
fontSize: 14,
fontStyle: 'italic',
fontWeight: 'bold',
fontFamily: 'Papyrus',
color: 'red',
maxLength: 25,
},
},
}
maxLength
constrains the length of the labels, after which the text will be truncated with ellipsis.
See the API Reference for more details about customising the appearance of the labels.
See Formatters for details about customising the label text.
Markers
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: {
showSeriesStroke: true,
marker: {
size: 20,
strokeWidth: 3,
shape: 'diamond', // 'circle', 'square', 'cross', 'plus', 'triangle'
},
line: {
strokeWidth: 4,
length: 10,
},
},
}
Line
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: {
showSeriesStroke: true,
line: {
strokeWidth: 4,
length: 15,
},
},
}
Series Visibility Toggling
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.
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.item.toggleSeriesVisible
property to false
.
legend: {
item: {
toggleSeriesVisible: false,
}
}
To prevent the last visible series from being hidden, use the preventHidingAll
option.
legend: {
preventHidingAll: true,
}
The legendItemClick
and legendItemDoubleClick
events can be used to listen to Legend item clicks and double clicks, respectively. For more information see Legend Events.
In this scenario, both the listener and the item toggle behaviour will occur. In the above example, clicking or double clicking a Legend item will toggle the series visibility as well as logging a message to the browser console via a legendItemClick
event.
API Reference
Properties available on the AgChartLegendOptions
interface.
Whether to show the legend. By default, the chart displays a legend when there is more than one series present.