Charts - Axis

Axis provides associate values to element positions.

Axes are used in the following charts: <LineChart />, <BarChart />, <ScatterChart />.

Defining axis

Like your data, axis definition plays a central role in the chart rendering. It's responsible for the mapping between your data and element positions.

You can define custom axes by using xAxis and yAxis props. Those props expect an array of objects.

Here is a demonstration with two lines with the same data. But one uses a linear, and the other a log axis.

Each axis definition is identified by its property id. And series specify the axis they use with xAxisKey and yAxisKey properties.

<LineChart
  xAxis={[{ data: sample }]}
  yAxis={[
    { id: 'linearAxis', scaleType: 'linear' },
    { id: 'logAxis', scaleType: 'log' },
  ]}
  series={[
    { yAxisKey: 'linearAxis', data: sample, label: 'linear' },
    { yAxisKey: 'logAxis', data: sample, label: 'log' },
  ]}
  leftAxis="linearAxis"
  rightAxis="logAxis"
  height={400}
/>

<LineChart
  xAxis={[{ data: sample }]}
  yAxis={[
    { id: 'linearAxis', scaleType: 'linear' },
    { id: 'logAxis', scaleType: 'log' },
  ]}
  series={[
    { yAxisKey: 'linearAxis', data: sample, label: 'linear' },
    { yAxisKey: 'logAxis', data: sample, label: 'log' },
  ]}
  leftAxis="linearAxis"
  rightAxis="logAxis"
  height={400}
/>

Press Enter to start editing

Axis type

The axis type is specified by its property scaleType which expect one of the following values:

'band': Split the axis in equal band. Mostly used for bar charts.
'linear', 'log', 'sqrt': Map numerical values to the space available for the chart. 'linear' is the default behavior.
'time', 'utc': Map JavaScript Date() object to the space available for the chart.

Axis data

The axis definition object also includes a data property. Which expects an array of value coherent with the scaleType:

For 'linear', 'log', or 'sqrt' it should contain numerical values
For 'time' or 'utc' it should contain Date() objects
For 'band' it can contain string, or numerical values

Some series types also require specific axis attributes:

line plots require an xAxis to have data provided
bar plots require an xAxis with scaleType='band' and some data provided.

Axis sub domain

By default, the axis domain is computed such that all your data is visible. To show a specific range of values, you can provide properties min and/or max to the axis definition.

xAxis={[{ min: 10, max: 50,  }]}

Ticks positions

You can customize the number of ticks with the property tickNumber.

As a helper, you can also provide tickMinStep and tickMaxStep which will compute tickNumber such that the step between two ticks respect those min/max values.

Here the top axis has a tickMinStep of half a day, and the bottom axis a tickMinStep of a full day.

<LineChart
  xAxis={[
    {
      ...xAxisCommon,
      tickMinStep: 3600 * 1000 * 24, // min step: 24h
    },
    {
      ...xAxisCommon,
      id: 'half days',
      tickMinStep: 3600 * 1000 * 12, // min step: 12hu
    },
  ]}
  {...config}
/>

<LineChart
  xAxis={[
    {
      ...xAxisCommon,
      tickMinStep: 3600 * 1000 * 24, // min step: 24h
    },
    {
      ...xAxisCommon,
      id: 'half days',
      tickMinStep: 3600 * 1000 * 12, // min step: 12hu
    },
  ]}
  {...config}
/>

Press Enter to start editing

Axis customization

You can further customize the axis rendering besides the axis definition.

Position

Charts components provide 4 props: topAxis, rightAxis, bottomAxis, and leftAxis allowing to define the 4 axes of the chart. Those pros can accept three type of value:

null to not display the axis
string which should correspond to the id of a xAxis for top and bottom. Or to the id of a yAxis for left and right.
object which will be passed as props to <XAxis /> or <YAxis />. It allows to specify which axis should be represent, and to customize the design of the axis.

<ScatterChart
  {...params}
  leftAxis={null}
  bottomAxis={null}
  topAxis={DEFAULT_X_AXIS_KEY}
  rightAxis={DEFAULT_Y_AXIS_KEY}
  margin={{ top: 30, bottom: 10 }}
/>

<ScatterChart
  {...params}
  leftAxis={null}
  bottomAxis={null}
  topAxis={DEFAULT_X_AXIS_KEY}
  rightAxis={DEFAULT_Y_AXIS_KEY}
  margin={{ top: 30, bottom: 10 }}
/>

Press Enter to start editing

Rendering

Axes rendering can be further customized. Below is an interactive demonstration of the axis props.

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

<ScatterChart
  {/** ... */}
  bottomAxis={{
  }}
/>

Playground

disableLine

disableTicks

label

tickSize

Composition

If you are using composition, you have to provide the axis settings in the <ChartContainer /> by using xAxis and yAxis props.

It will provide all the scaling properties to its children, and allows you to use <XAxis/> and <YAxis/> components as children. Those components require an axisId prop to link them to an axis you defined in the <ChartContainer />.

You can choose their position with position props which accept 'top'/'bottom' for <XAxis /> and 'left'/'right' for <YAxis />. Other props are similar to the ones defined in the previous section.