Skip to main content

​
Overview

The Legend class creates an interactive legend that displays chart series or data items with toggleable visibility. It automatically generates legend items with markers, labels, and value labels.

​
Constructor

Legend.new(root, settings)
​
root
Root
required
The root element of the chart
​
settings
ILegendSettings
Configuration settings for the legend

​
Settings

​
Marker Settings

​
useDefaultMarker
boolean
default:"false"
If true, the legend will show default square markers instead of mimicking the appearance of actual chart items.

​
Data Field Settings

​
nameField
string
Key to look up in data for the name of the data item.
​
fillField
string
Key to look up in data for the fill color of the data item.
​
strokeField
string
Key to look up in data for the stroke color of the data item.

​
Interaction Settings

​
clickTarget
'itemContainer' | 'marker' | 'none'
default:"'itemContainer'"
Which legend item element will be clickable to toggle the related chart item.
  • itemContainer - The whole legend item (default)
  • marker - Only the legend item marker
  • none - Disables toggling

​
Properties

​
itemContainers

​
itemContainers
ListTemplate<Container>
List template of all Container elements for legend items. Use to customize item container appearance.
legend.itemContainers.template.setAll({
  paddingTop: 5,
  paddingBottom: 5
});

​
markers

​
markers
ListTemplate<Container>
List template of legend marker elements. Use to customize marker appearance.
legend.markers.template.setAll({
  width: 20,
  height: 20
});

​
labels

​
labels
ListTemplate<Label>
List template of legend label elements. Use to customize label text.
legend.labels.template.setAll({
  fontSize: 12,
  fontWeight: "bold"
});

​
valueLabels

​
valueLabels
ListTemplate<Label>
List template of legend value label elements. Use to display and customize values.
legend.valueLabels.template.setAll({
  fontSize: 10,
  fill: am5.color(0x999999)
});

​
markerRectangles

​
markerRectangles
ListTemplate<RoundedRectangle>
List template of rectangle elements used for default legend markers.
legend.markerRectangles.template.setAll({
  cornerRadiusTL: 5,
  cornerRadiusTR: 5,
  cornerRadiusBL: 5,
  cornerRadiusBR: 5
});

​
Methods

​
makeItemContainer()

Creates a container for a legend item. 
makeItemContainer(dataItem: DataItem<ILegendDataItem>): Container
​
dataItem
DataItem<ILegendDataItem>
required
The data item for this legend entry
​
returns
Container
The created item container

​
makeMarker()

Creates a marker element for a legend item. 
makeMarker(): Container
​
returns
Container
The created marker container

​
makeLabel()

Creates a label element for a legend item. 
makeLabel(): Label
​
returns
Label
The created label

​
makeValueLabel()

Creates a value label element for a legend item. 
makeValueLabel(): Label
​
returns
Label
The created value label

​
makeMarkerRectangle()

Creates a rectangle element for default marker. 
makeMarkerRectangle(): RoundedRectangle
​
returns
RoundedRectangle
The created marker rectangle

​
Data Item Structure

Each legend data item contains:
​
itemContainer
Container
Container holding all legend item elements
​
marker
Container
Marker element
​
markerRectangle
RoundedRectangle
Marker rectangle element
​
label
Label
Label element
​
valueLabel
Label
Value label element
​
fill
Color
Marker fill color
​
stroke
Color
Marker stroke color
​
name
string
Name of the legend item

​
Examples

​
Basic Legend

import { Legend } from "@amcharts/amcharts5";

const legend = chart.children.push(
  Legend.new(root, {
    centerX: am5.percent(50),
    x: am5.percent(50)
  })
);

legend.data.setAll(chart.series.values);

​
Legend with Custom Markers

const legend = Legend.new(root, {
  useDefaultMarker: true
});

legend.markerRectangles.template.setAll({
  width: 15,
  height: 15,
  cornerRadiusTL: 7.5,
  cornerRadiusTR: 7.5,
  cornerRadiusBL: 7.5,
  cornerRadiusBR: 7.5
});

legend.data.setAll(chart.series.values);

​
Legend with Custom Labels

const legend = Legend.new(root, {});

legend.labels.template.setAll({
  fontSize: 14,
  fontWeight: "600",
  fill: am5.color(0x000000)
});

legend.data.setAll(chart.series.values);

​
Legend with Value Labels

const legend = Legend.new(root, {});

legend.valueLabels.template.setAll({
  fontSize: 12,
  textAlign: "right",
  text: "{valueY}"
});

legend.data.setAll(chart.series.values);

​
Legend with Marker-Only Clicking

const legend = Legend.new(root, {
  clickTarget: "marker"
});

legend.data.setAll(chart.series.values);

​
Vertical Legend

const legend = chart.rightAxesContainer.children.push(
  Legend.new(root, {
    layout: root.verticalLayout,
    height: am5.percent(100),
    verticalScrollbar: am5.Scrollbar.new(root, {
      orientation: "vertical"
    })
  })
);

legend.data.setAll(chart.series.values);

​
Legend with Custom Data

const legend = Legend.new(root, {
  nameField: "categoryName",
  fillField: "categoryColor"
});

legend.data.setAll([
  { categoryName: "Apples", categoryColor: am5.color(0xff0000) },
  { categoryName: "Oranges", categoryColor: am5.color(0xff9900) },
  { categoryName: "Bananas", categoryColor: am5.color(0xffff00) }
]);

​
Legend with Custom Item Spacing

const legend = Legend.new(root, {
  layout: root.horizontalLayout
});

legend.itemContainers.template.setAll({
  paddingLeft: 10,
  paddingRight: 10
});

legend.data.setAll(chart.series.values);

​
Toggling Items

Legend items are automatically interactive. Clicking an item will:
  1. Call hide() on the associated chart element if it’s visible
  2. Call show() on the associated chart element if it’s hidden
  3. Apply a “disabled” state to the legend item container
  4. Announce the change to screen readers

​
Styling with States

Legend items automatically get a “disabled” state when toggled off: 
legend.itemContainers.template.states.create("disabled", {
  opacity: 0.5
});

legend.labels.template.states.create("disabled", {
  fill: am5.color(0x999999)
});

Build docs developers (and LLMs) love

Get started for freeTalk to us