Charts - Custom components

Creating custom chart components is made easier by hooks.

Interact with dimensions

Drawing area

Charts dimensions are defined by a few props:

height and width for the <svg /> size. If not provided, those values are derived from the container.
margin for adding space between the <svg /> border and the drawing area.

The term drawing area refers to the space available to plot data (scatter points, lines, or pie arcs). The margin is used to leave some space for extra elements, such as the axes, the legend, or the title.

You can use the useDrawingArea() hook in the charts subcomponents to get the coordinates of the drawing area.

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

const { left, top, width, height } = useDrawingArea();

<ChartContainer
  margin={{ top: 20, left: 10, right: 10, bottom: 30 }}
  height={300}
  series={[
    {
      type: 'line',
      data: [13, 13, 54, 651, 657, 987, 64, 654, 954, 654, 897, 84],
    },
  ]}
  xAxis={[{ data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }]}
>
  <LinePlot />
  <DrawingAreaBox />
</ChartContainer>

<ChartContainer
  margin={{ top: 20, left: 10, right: 10, bottom: 30 }}
  height={300}
  series={[
    {
      type: 'line',
      data: [13, 13, 54, 651, 657, 987, 64, 654, 954, 654, 897, 84],
    },
  ]}
  xAxis={[{ data: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12] }]}
>
  <LinePlot />
  <DrawingAreaBox />
</ChartContainer>

Press Enter to start editing

Scales

Some charts, such as line, bar, and scatter do a mapping between their series' data and the SVG coordinates.

For example, a line chart series with a value of 36,725$ on the 6th of December 2022 could be mapped to coordinates (628, 514). This operation can be reversed. Coordinate with x=628 would be associated with the 6th of December 2022 and y=514 would be associated with value 36,725$.

Those mappings depend on the dimensions of the SVG and the drawing area. It also depends on the axes' properties such as the scale (linear, log, square root) and min/max values.

All that data is available in the d3-scale objects.

You can use useXScale() and useYScale() to access those scales. Both accept either:

a number to select the index of the axis to select.
a string to select an axis by its id.

The scale object is generated such that it maps values to SVG coordinates. You don't need extra work to take into account the drawing area.

Value to coordinate

The d3-scale default method maps from values to coordinates. For example, you can get the x=0 coordinate as follows:

const xAxisScale = useXScale(); // get the default X scale
const xOrigin = xAxisScale(0);

Coordinate to value

The d3-scale object allows you to convert a coordinate to a data value with the invert method.

The next example contains two lines drawn using different y-axes. By using invert, the value associated with the current mouse coordinate y can be resolved as follows:

<text>{leftAxisScale.invert(yCoordinate).toFixed(0)}</text>

HTML components

With the introduction of the ChartDataProvider in v8, the chart data can be accessed from any component. This allows you to create HTML components that interact with the charts data.

In the next example, notice that MyCustomLegend component displays the series names and colors. This creates an html table element, which handles long series names better than the default legend.

	First Series
	Second Series. You should always try to avoid long sentences. But oftentimes, it's not possible. So, we need to handle them gracefully. This is a very long sentence that should be fully readable.

<ChartDataProvider
  series={[
    { label: 'First Series', type: 'bar', data: [100, 200] },
    { label: veryLongText, type: 'bar', data: [45, 333] },
  ]}
  xAxis={[{ data: ['A', 'B'], scaleType: 'band', id: 'x-axis' }]}
>
  <ChartsSurface>
    <BarPlot />
    <ChartsXAxis position="bottom" axisId="x-axis" />
    <ChartsYAxis position="left" />
  </ChartsSurface>
  <MyCustomLegend />
</ChartDataProvider>

<ChartDataProvider
  series={[
    { label: 'First Series', type: 'bar', data: [100, 200] },
    { label: veryLongText, type: 'bar', data: [45, 333] },
  ]}
  xAxis={[{ data: ['A', 'B'], scaleType: 'band', id: 'x-axis' }]}
>
  <ChartsSurface>
    <BarPlot />
    <ChartsXAxis position="bottom" axisId="x-axis" />
    <ChartsYAxis position="left" />
  </ChartsSurface>
  <MyCustomLegend />
</ChartDataProvider>

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.