Legend

The Legend component is used to display a legend for the visualization.

<Chart data={data}>
    <Legend position="right" title="Country">
</Chart>

Props

name	type	default	description
color	string | {value: Color}	–	Overrides the default symbol fill and stroke color. If a string is provided, this is a data key reference, similar to setting color on a mark like Line or Bar. If a static value object is provided then all symbols will be the color provided. Css color names and spectrum color names are supported for the static color value.
defaultHiddenSeries	string[]	–	Series that should be hidden by default (uncontrolled). This is different from hiddenEntries which only hides entries from the legend, whereas defaultHiddenSeries hides the series from both the legend and the chart.
descriptions	{seriesName: string, description: string, title?: string}[]	–	An array of objects containing a seriesName, description, and optional title property. The seriesName must match the value of the series property on the chart data being passed in. If set, a tooltip will appear after a short delay when you hover over a legend element. The contents of the tooltip will be the description found in the key-value pair.
hiddenEntries	string[]	–	List of series names that should be hidden from the legend. This does not hide these series in the chart as well, only the legend. To hide series in the chart, use hiddenSeries.
highlight	boolean	false	Defines if hovering over a legend element should highlight that series in the chart.
isToggleable	boolean	false	Sets if the series should be able to hide/show by clicking on the respective legend entry (uncontrolled).
keys	string[]	–	Keys from the data to generate the legend for. Defaults to all keys used to facet the data. Use this prop to limit which data fields should appear in the legend.
labelLimit	number	–	Max width in pixels before truncating a legend label. If not specified, labels will not be truncated. Influences legend column layout by calculating how many legend items can fit horizontally based on the label width (for top/bottom positioned legends).
legendLabels	{seriesName: string | number, label: string, maxLength?: number}[]	-	Defines custom labels to display in place of the series value for data. If one series has an override, any series that don't have an override will display their series value. The optional maxLength property can be used to truncate individual labels.
lineType	string | { value: LineType }	–	Overrides the default symbol border line type. If a string is provided, this is a data key reference, similar to setting color on a mark like Line or Bar. If a static value object is provided then all symbol borders will have the line type provided.
lineWidth	string | { value: LineWidth }	–	Overrides the default symbol border line width. If a string is provided, this is a data key reference, similar to setting color on a mark like Line or Bar. If a static value object is provided then all symbol borders will have the line width provided.
onMouseOut	(seriesName: string) => void	–	Allows triggering of a callback function when moving the mouse pointer outside of a legend item.
onMouseOver	(seriesName: string) => void	–	Allows triggering of a callback function when moving the mouse pointer over a legend item.
opacity	string | { value: number }	–	Overrides the default symbol fill opacity. If a string is provided, this is a data key reference, similar to setting color on a mark like Line or Bar. If a static value object is provided then all symbols will have the fill opacity provided.
position	'left' | 'bottom' | 'top' | 'right'	'bottom'	Sets where the legend will be displayed.
symbolShape	string | { value: ChartSymbolShape }	–	Overrides the default symbol shape. If a string is provided, this is a data key reference, similar to setting color on a mark like Line or Bar. If a static value object is provided then all symbols will be the shape provided.
title	string	–	Defines the legend title.
titleLimit	number	–	The maximum allowed length in pixels of the legend title. If the title exceeds this length, it will be truncated.

Hide/Show Series

The legend component can be used to hide and show series in the chart. These series will still appear in the legend but the data for these series will not be drawn.

If there is a need to hide a given series in the chart as well as in the legend, it is recommended to filter that data from the data array supplied to the Chart component.

Uncontrolled

The easiest way to hide/show data in the chart is to supply the isToggleable prop to the legend. isToggleable sets up the legend entries so that each works like a toggle input that will hide/show the respective series.

Example

<Chart>
  <Bar />
  <Legend isToggleable />
</Chart>

Controlled

It is also possible to hide/show series using a controlled approach. This is useful if there is a need to toggle the visibility of series from an external input or if complex hide/show logic is needed.

To setup hide/show using a controlled method, pass in the list of hidden series to the hiddenSeries prop. Note that the hidden series values should be the series name and not a custom series label that might have been provided using the legendLabels prop.

The onClick handler can be used to trigger custom hide/show logic.

Example

const [hiddenSeries, setHiddenSeries] = useState<string[]>([])

const onLegendClick = (seriesName: string) => {
  if (hiddenSeries.includes(seriesName)) {
    setHiddenSeries(hiddenSeries.filter(series => series !== seriesName))
  }
  setHiddenSeries([...hiddenSeries, seriesName])
}

return (
  <Chart hiddenSeries={hiddenSeries}>
    <Bar/>
    <Legend onClick={onLegendClick} />
  </Chart>
)

Advanced

Faceting Data

It is possible to control the symbols for legend entries beyond the default styles that get applied based on the visualization. By default the legend symbol color, border line type, border line width, opacity, and shape are inferred from the mark that they represent.

If there is a need to override any of these, the color, lineType, lineWidth, and opacity props can be used. If a string is provided to any of these, then it will use that data key to facet the data. If a static value object is provided (\{value: any}), then that static value will be applied to all symbols.

Example

For the following example, each symbol in the legend will be gray-800 and the opacity of each symbol will be determined by the operatingSystem.

<Chart>
  <Bar />
  <Legend color={{ value: 'gray-800' }} opacity="operatingSystem" />
</Chart>