Charts - Legend

Legend is the UI element mapping symbols and colors to the series' label.

Basic display

In chart components, the legend links series with label properties and their color.

<ScatterChart
  series={[
    { type: 'scatter', label: 'Var A', data: data.slice(0, 25) },
    { type: 'scatter', label: 'Var B', data: data.slice(25) },
  ]}
  width={400}
  height={300}
/>

<ScatterChart
  series={[
    { type: 'scatter', label: 'Var A', data: data.slice(0, 25) },
    { type: 'scatter', label: 'Var B', data: data.slice(25) },
  ]}
  width={400}
  height={300}
/>

Press Enter to start editing

Customization

Position

The legend can either be displayed in a 'column' or 'row' layout controlled with the direction property.

It can also be moved with the position: { vertical, horizontal } property which defines how the legend aligns within the SVG.

vertical can be 'top', 'middle', or 'bottom'.
horizontal can be 'left', 'middle', or 'right'.

You can add spacing to a given position with the padding property, which can be either a number or an object { top, bottom, left, right }. This padding will add space between the SVG borders and the legend.

By default, the legend is placed above the charts.

import { PieChart } from '@mui/x-charts/PieChart';

<PieChart
  margin={{ top: 100, bottom: 100, left: 100, right:100 }}
  {/** ... */}
  slotProps={{
    legend: {
      direction: 'undefined',
      position: { vertical: 'undefined', horizontal: 'undefined' },
      padding: undefined,
    },
  }}
/>

Playground

direction

vertical

horizontal

padding

itemsNumber

Hiding

You can hide the legend with the property slotProps.legend.hidden.

hide the legend

<FormControlLabel
  checked={isHidden}
  control={
    <Checkbox onChange={(event) => setIsHidden(event.target.checked)} />
  }
  label="hide the legend"
  labelPlacement="end"
/>
<PieChart
  series={series}
  slotProps={{ legend: { hidden: isHidden } }}
  width={400}
  height={200}
/>

<FormControlLabel
  checked={isHidden}
  control={
    <Checkbox onChange={(event) => setIsHidden(event.target.checked)} />
  }
  label="hide the legend"
  labelPlacement="end"
/>
<PieChart
  series={series}
  slotProps={{ legend: { hidden: isHidden } }}
  width={400}
  height={200}
/>

Press Enter to start editing

Dimensions

Inside the legend, you can customize the pixel value of the width and height of the mark with the itemMarkWidth and itemMarkHeight props.

You can also access the markGap prop to change the gap between the mark and its label, or the itemGap to change the gap between two legend items. Both props impact the values defined in pixels.

import { PieChart } from '@mui/x-charts/PieChart';

<PieChart
  margin={{ top: 100, bottom: 10, left: 10, right:100 }}
  {/** ... */}
  slotProps={{
    legend: {
      direction: props.direction,
      position: {
        vertical: 'middle',
        horizontal: 'right',
      },
      itemMarkWidth: undefined,
      itemMarkHeight: undefined,
      markGap: undefined,
      itemGap: undefined,
    }
  }}
/>

Playground

direction

itemMarkWidth

itemMarkHeight

markGap

itemGap

Label styling

To break lines in legend labels, use the special \n character. To customize the label style, you should not use CSS. Instead, pass a styling object to the labelStyle property.

import { PieChart } from '@mui/x-charts/PieChart';

<PieChart
  margin={{ top: 100, bottom: 10, left: 10, right:100 }}
  {/** ... */}
  series={[
    { ..., label: 'series A'}
    ...
  ]}
  slotProps={{
    legend: {
      labelStyle: {
        fontSize: undefined,
        fill: 'undefined',
      },
    },
  }}
/>

Playground

fontSize

fill

breakLine

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.