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.

  • Var A
  • Var B
−20−15−10−505101520−20−1001020
Press Enter to start editing

Customization

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

Dimensions

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

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: 'middle'
      }
    }
  }}
/>

Playground

Hiding

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

  • series A
  • series B
  • series C
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

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

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
Press Enter to start editing

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 show how to use it with slots. 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
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
  {/** ... */}
  margin={{ top: 20, right: 20 }}
  slots={{ legend: ContinuousColorLegend }}
  slotProps={{
    legend: {
      axisDirection: 'y',
      direction: 'horizontal',
      thickness: 12,
      labelPosition: 'end',
      reverse: false,
      sx: { width: '50%' },
    },
  }}
/>

Playground

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
  {/** ... */}
  margin={{ top: 20, right: 20 }}
  slots={{ legend: PiecewiseColorLegend }}
  slotProps={{
    legend: {
      axisDirection: 'x',
      direction: 'horizontal',
      markType: 'square',
      labelPosition: 'extremes',
      sx: { padding: 0 },
    },
  }}
/>

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

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.