Charts - Legend

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

Customization

This section explains how to customize the legend using classes and properties.

Much of the customization can be done using CSS properties. There is a main class for the legend container, .MuiChartsLegend-root. Alternatively the legendClasses variable can be used if using CSS-in-JS to target the elements.

Each legend item is composed of two main elements: the mark and the label.

The example below explains how it is possible to customize some parts the legend. And shows how to use both the legendClasses variable and the CSS class directly.

Series A
Series B
Series C
Series D
Series E
Series F
Series G
Series H

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

<PieChart
  {/** ... */}
  slotProps={{
    legend: {
      direction: props.direction,
      sx: {
        gap: '16px',
        // CSS-in-JS
        [`.${legendClasses.mark}`]: {
          height: 15,
          width: 15,
        },
        // CSS class
        ['.MuiChartsLegend-series']: {
          gap: '8px',
        },
      },
    },
  }}
/>

Playground

direction

markSize

markGap

itemGap

Position

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

It can also be moved with the position: { vertical, horizontal } property which defines how the legend aligns itself in the parent container.

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

By default, the legend is placed above the charts.

Series A
Series B
Series C

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

<PieChart
  {/** ... */}
  slotProps={{
    legend: {
      direction: 'vertical',
      position: { 
        vertical: 'middle',
        horizontal: 'center'
      }
    }
  }}
/>

Playground

direction

vertical

horizontal

itemsNumber

Hiding

You can hide the legend with the hideLegend prop of the Chart.

hide the legend

series A
series B
series C

{Toggle}
<PieChart series={series} hideLegend={isHidden} width={200} height={200} />

{Toggle}
<PieChart series={series} hideLegend={isHidden} width={200} height={200} />

Press Enter to start editing

Label styling

Changing the label style can be done by targeting the root component's font properties.

To change the mark color or shape, the fill class is used instead. Keep in mind that the mark is an SVG element, so the fill property is used to change its color.

Series A
Series B
Series C
Series D

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

<PieChart
  {/** ... */}
  slotProps={{
    legend: {
      sx: {
        fontSize: 14,
        color: blue,
        [`.${labelMarkClasses.fill}`]: {
          fill: blue,
        },
      },
    },
  }}
/>

Playground

fontSize

color

markColor

Change mark shape

To change the mark shape, you can use the labelMarkType property of the series item. For the pie series, the labelMarkType property is available for each of the pie slices too.

Series A
Series B
Series C
Series D

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

<BarChart
  {/** ... */}
  series={
    seriesConfig.map((seriesItem) => ({
      ...seriesItem,
      labelMarkType: 'square',
    }))
  }
/>

Playground

markType

Custom shapes

For more advanced use cases, you can also provide a component to the labelMarkType property of each series to fully customize the mark.

Series A
Series B
Series C
Series D

<BarChart
  series={[
    { id: 0, data: [10, 15], label: 'Series A', labelMarkType: HTMLCircle },
    { id: 1, data: [15, 20], label: 'Series B', labelMarkType: 'line' },
    { id: 2, data: [20, 25], label: 'Series C' },
    { id: 3, data: [10, 15], label: 'Series D', labelMarkType: SVGDiamond },
  ]}
  xAxis={[{ data: ['Category 1', 'Category 2'] }]}
  height={200}
/>

<BarChart
  series={[
    { id: 0, data: [10, 15], label: 'Series A', labelMarkType: HTMLCircle },
    { id: 1, data: [15, 20], label: 'Series B', labelMarkType: 'line' },
    { id: 2, data: [20, 25], label: 'Series C' },
    { id: 3, data: [10, 15], label: 'Series D', labelMarkType: SVGDiamond },
  ]}
  xAxis={[{ data: ['Category 1', 'Category 2'] }]}
  height={200}
/>

Press Enter to start editing

Passing a component to labelMarkType affects not only the legend but other places where the label mark is shown, such as tooltips.

Customizing the mark shape of a pie chart depending on the series is slightly different. You can find how to do it in this example.

To ensure compatibility with gradients and patterns, consider using SVG instead of HTML in the labelMarkType.

Scrollable legend

The legend can be made scrollable by setting the overflowY for vertical legends or overflowX for horizontal legends. Make sure that the legend container has a fixed height or width to enable scrolling.

Series A
Series B
Series C
Series D
Series E
Series F
Series G
Series H
Series I
Series J
Series K
Series L
Series M
Series N
Series O

<PieChart
  series={series}
  sx={{
    height: '100%',
  }}
  slotProps={{
    legend: {
      sx: {
        overflowY: 'scroll',
        flexWrap: 'nowrap',
        height: '100%',
      },
    },
  }}
/>

<PieChart
  series={series}
  sx={{
    height: '100%',
  }}
  slotProps={{
    legend: {
      sx: {
        overflowY: 'scroll',
        flexWrap: 'nowrap',
        height: '100%',
      },
    },
  }}
/>

Press Enter to start editing

Series styling

You can use CSS to style the series in the legend. Each legend item has a data-series attribute where its value is the ID of the series it represents.

Product A
Product B

Custom component

For advanced customization, you can create your own legend with useLegend. This hook returns the items that the default legend would plot. Allowing you to focus on the rendering.

This demo also shows how to use labelMarkType together with a custom legend to create a legend with custom shapes.

This approach uses slots to render the legend items. Another demo in HTML components docs shows how to use it with composition.

temp. avg. 1991-2020 (°C)

temp. 2023 (°C)

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'.

Then it is possible to override the legend slot to display the wanted legend, or use the composition API to add as many legends as needed.

<1961
>1990

<LineChart
  {...data}
  xAxis={[
    {
      ...data.xAxis![0],
      colorMap: {
        type: 'piecewise',
        thresholds: [new Date(1961, 0, 1), new Date(1990, 0, 1)],
        colors: ['blue', 'gray', 'red'],
      },
    },
  ]}
  slots={{ legend: PiecewiseColorLegend }}
  slotProps={{ legend: { axisDirection: 'x' } }}
/>

<LineChart
  {...data}
  xAxis={[
    {
      ...data.xAxis![0],
      colorMap: {
        type: 'piecewise',
        thresholds: [new Date(1961, 0, 1), new Date(1990, 0, 1)],
        colors: ['blue', 'gray', 'red'],
      },
    },
  ]}
  slots={{ legend: PiecewiseColorLegend }}
  slotProps={{ legend: { axisDirection: 'x' } }}
/>

Press Enter to start editing

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

>1990
<1961

Position

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

Label position

The labels can be positioned in relation to the marks or gradient with the labelPosition prop. The values accepted are 'start', 'end' or 'extremes'.

With direction='horizontal', using 'start' places the labels above the visual marker, while end places them below.
When direction='vertical', is 'start' or 'end' the labels are positioned left and right of the visual markers, respectively.
With the 'extremes' value, the labels are positioned at both the beginning and end of the visual marker.

Continuous

Horizontal

start

-0.5°
1.5°

end

-0.5°
1.5°

extremes

-0.5°
1.5°

Vertical

start

-0.5°
1.5°

end

-0.5°
1.5°

extremes

-0.5°
1.5°

Piecewise

Horizontal

start

<0°
>1.5°

end

<0°
>1.5°

extremes

<0°
>1.5°

Vertical

start

>1.5°
0°-1.5°
<0°

end

>1.5°
0°-1.5°
<0°

extremes

>1.5°
<0°

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 parent dimension.

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

It is also possible to reverse the gradient with the reverse prop.

-0.5°
1.5°

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

<LineChart
  {/** ... */}
  slots={{ legend: ContinuousColorLegend }}
  slotProps={{
    legend: {
      axisDirection: 'y',
      direction: 'horizontal',
      thickness: 12,
      labelPosition: 'end',
      reverse: false,
      sx: { width: '50%' },
    },
  }}
/>

Playground

direction

labelPosition

length

thickness

reverse

Piecewise color mapping

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

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. Returning an empty string removes any label, but still display the mark.

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

The markType can be changed with the markType prop. Since the color values are based on the axis, and not the series, the markType has to be set directly on the legend.

<1961
>1990

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

<LineChart
  {/** ... */}
  slots={{ legend: PiecewiseColorLegend }}
  slotProps={{
    legend: {
      axisDirection: 'x',
      direction: 'horizontal',
      markType: 'square',
      labelPosition: 'extremes',
      sx: { padding: 0 },
    },
  }}
/>

Playground

direction

labelPosition

markType

onlyShowExtremes

padding

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

Piecewise Color 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.

Charts - Legend

Basic display

Customization

Dimensions

Playground

Position

Playground

Hiding

Label styling

Playground

Change mark shape

Playground

Custom shapes

Scrollable legend

Series styling

Custom component

Color legend

Select data

Position

Label position

Continuous

Horizontal

Vertical

Piecewise

Horizontal

Vertical

Continuous color mapping

Playground

Piecewise color mapping

Playground

Click event

API