Skip to content
+

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.

−20−15−10−505101520−20−1001020
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: 'row',
      position: { vertical: 'top', horizontal: 'middle' },
      padding: 0,
    },
  }}
/>

Playground

Hiding

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

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: 20,
      itemMarkHeight: 2,
      markGap: 5,
      itemGap: 10,
    }
  }}
/>

Playground

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: 14,
        fill: 'blue',
      },
    },
  }}
/>

Playground

Color legend

To display legend associated to a colorMap, you can use:

  • <ContinuousColorLegend /> if you're using colorMap.type='continuous'
  • <PiecewiseColorLegend /> if you're using colorMap.type='piecewise'.

Select data

To select the color mapping to represent, use the following props:

  • axisDirection can be 'x', 'y', or 'z'. It indicates which axis contain the colorMap definition.
  • axisId The id of the axis to use in case the selected direction contains multiple ones.

Global temperature anomaly relative to 1961-1990 average

Position

This component position is done exactly the same way as the legend for series.

Continuous color mapping

To modify the shape of the gradient, use the length and thickness props. The length can either be a number (in px) or a percentage string. The "100%" corresponds to the SVG dimension.

To format labels use the minLabel/maxLabel. They accept either a string to display. Or a function ({value, formattedValue}) => string.

The labels and gradient bar alignment can be modified by the align prop.

import { LineChart } from '@mui/x-charts/LineChart';
import { ContinuousColorLegend } from '@mui/x-charts/ChartsLegend';

<LineChart
  margin={{ top: 50, right: 20 }}
  {/** ... */}
>
  <ContinuousColorLegend
      axisDirection="x"
      position={{ vertical: 'top', horizontal: 'middle' }}
      direction="row"
      length="50%"
      thickness={5}
      align="middle"
      labelStyle={{ fontSize: 10 }}
    />
</LineChart>

Playground

Piecewise color mapping

The piecewise Legend is quite similar to the series legend. It accepts the same props for customization.

The props hideFirst and hideLast allows to hide the two extreme pieces: values lower than the min threshold, and value higher than the max threshold.

To override labels generated by default, provide a labelFormatter prop. It takes the min/max of the piece and returns the label.

Values can be null for the first and last pieces. And returning null removes the piece from the legend.

labelFormatter = ({ min, max, formattedMin, formattedMax }) => string | null;

import { LineChart } from '@mui/x-charts/LineChart';
import { PiecewiseColorLegend } from '@mui/x-charts/ChartsLegend';

<LineChart
  margin={{ top: 50, right: 20 }}
  {/** ... */}
>
  <PiecewiseColorLegend
      axisDirection="x"
      position={{ vertical: 'top', horizontal: 'middle' }}
      direction="row"
      padding={0}
      labelStyle={{ fontSize: 10 }}
    />
</LineChart>

Playground

Click event

You can pass an onItemClick function to the ChartsLegend or PiecewiseColorLegend components to handle click events. They both provide the following signature.

const clickHandler = (
  event, // The click event.
  context, // An object that identifies the clicked item.
  index, // The index of the clicked item.
) => {};

The context object contains different properties depending on the legend type. Click the legend items to see their content.

Chart Legend

Pie Chart Legend

Pie Chart Legend

Click on the chart

// Index from item click: 

// Context from item click
// The data will appear here

API

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