Charts - Reference elements

Add visual markers to add extra context to your charts.

Reference elements are visual markers overlaid on charts to draw attention to notable data values. They help users interpret data by providing context such as thresholds, target values, acceptable ranges, or specific data points of interest.

This page contains demonstrations about three types of reference element.

Reference line: A line drawn across the chart at a specific value on an axis.
Reference area: A shaded region between two values on an axis.
Reference point: A marker placed at a specific coordinate.

US unemployment rate comparison with GDP per capita

Unemployment rate
GDP per capita

MUI X Missing license key

Source: FRED

Reference line

The <ChartsReferenceLine /> component draws a horizontal or vertical line at a given value. Common use cases include marking thresholds, averages, or targets.

Provide an x prop for a vertical line or a y prop for a horizontal line.

<LineChart {...chartsConfig}>
  <ChartsReferenceLine y={4} />
  <ChartsReferenceLine x="Mar" />
</LineChart>

<LineChart {...chartsConfig}>
  <ChartsReferenceLine y={4} />
  <ChartsReferenceLine x="Mar" />
</LineChart>

Press Enter to start editing

Label

You can add a label prop to display text alongside the reference line. Position it with the labelAlign prop, which accepts 'start', 'middle' (default), and 'end'.

<LineChart {...chartsConfig}>
  <ChartsReferenceLine y={7} label="Max" labelAlign="end" />
  <ChartsReferenceLine y={4} label="Average" labelAlign="middle" />
  <ChartsReferenceLine
    y={1}
    label="Min"
    labelAlign="start"
    // Move label below the line.
    spacing={{ y: -5 }}
    labelStyle={{ dominantBaseline: 'hanging' }}
  />
</LineChart>

<LineChart {...chartsConfig}>
  <ChartsReferenceLine y={7} label="Max" labelAlign="end" />
  <ChartsReferenceLine y={4} label="Average" labelAlign="middle" />
  <ChartsReferenceLine
    y={1}
    label="Min"
    labelAlign="start"
    // Move label below the line.
    spacing={{ y: -5 }}
    labelStyle={{ dominantBaseline: 'hanging' }}
  />
</LineChart>

Press Enter to start editing

Styling

You can style the ChartsReferenceLine with two ways

Using CSS classes thanks to the referenceLineClasses
Use the lineStyle and labelStyle props that are style object passed to the line and the label.

Using the labelStyle is necessary if you your label has multiple lines. This property is used to measure the text size and correctly space the multiple lines.

<LineChart {...chartsConfig}>
  <StyledReferenceLine
    y={6}
    label="Threshold"
    labelAlign="start"
    labelStyle={{ fill: 'red', fontSize: 12 }}
  />
  <ChartsReferenceLine
    x="Apr"
    label="Target"
    lineStyle={{ stroke: 'green', strokeWidth: 2 }}
    labelStyle={{ fill: 'green', fontSize: 12 }}
    labelAlign="end"
  />
</LineChart>

<LineChart {...chartsConfig}>
  <StyledReferenceLine
    y={6}
    label="Threshold"
    labelAlign="start"
    labelStyle={{ fill: 'red', fontSize: 12 }}
  />
  <ChartsReferenceLine
    x="Apr"
    label="Target"
    lineStyle={{ stroke: 'green', strokeWidth: 2 }}
    labelStyle={{ fill: 'green', fontSize: 12 }}
    labelAlign="end"
  />
</LineChart>

Press Enter to start editing

Reference area

The next demo shows the implementation of a reference area between points (x1, y1) and (x2, y2).

Coordinates can either be axis values, or 'start'/'end' to extend the area to the min or max of the axis domain. Omitted coordinates also default to the full axis range.

For customization, use the associated useReferenceArea() which returns the coordinates of the rectangle. This allows for example adding some labels to the area.

Notice the usage of composition to be able to put the reference area below the plots.

command
response

Reference point

With the same logic as the previous section, you can highlight specific points in the chart.

<LineChart {...chartsConfig}>
  <ReferencePoint x="Apr" y={7} r={6} fill="red" />
  <ReferencePoint
    x="Jun"
    y={6}
    r={8}
    fill="none"
    stroke="green"
    strokeWidth={2}
  />
</LineChart>

<LineChart {...chartsConfig}>
  <ReferencePoint x="Apr" y={7} r={6} fill="red" />
  <ReferencePoint
    x="Jun"
    y={6}
    r={8}
    fill="none"
    stroke="green"
    strokeWidth={2}
  />
</LineChart>

Press Enter to start editing

API

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

<ChartsReferenceLine />