Charts - Getting Started

Get started with the MUI X Charts components. Install the package, configure your application, and start using the components.

Installation

Run one of the following commands to add the MUI X Charts to your project:

The Charts package has a peer dependency on @mui/material. If you are not already using it in your project, you can install it with:

Please note that react and react-dom are peer dependencies too:

"peerDependencies": {
  "react": "^17.0.0 || ^18.0.0",
  "react-dom": "^17.0.0 || ^18.0.0"
},

Style engine

Material UI is using Emotion as a styling engine by default. If you want to use styled-components instead, run:

Take a look at the Styled engine guide for more information about how to configure styled-components as the style engine.

Usage with Next.js

If you're using MUI X Charts with Next.js, you might face the following error:

[ESM][charts] Doesn't build due to require() of ES Module (ERR_REQUIRE_ESM)

To solve it, transpile the package by adding transpilePackages: ['@mui/x-charts'] to your next.config.js file. Visit this GitHub issue and comment for details.

Displaying Charts

A Chart can be rendered in one of two ways: as a single component, or by composing subcomponents.

Single Charts

For common use cases, the single component is the recommended way. Those components' names end with "Chart", as opposed to "Plot", and only require the series prop describing the data to render.

<BarChart
  xAxis={[
    {
      id: 'barCategories',
      data: ['bar A', 'bar B', 'bar C'],
      scaleType: 'band',
    },
  ]}
  series={[
    {
      data: [2, 5, 3],
    },
  ]}
  width={500}
  height={300}
/>

<BarChart
  xAxis={[
    {
      id: 'barCategories',
      data: ['bar A', 'bar B', 'bar C'],
      scaleType: 'band',
    },
  ]}
  series={[
    {
      data: [2, 5, 3],
    },
  ]}
  width={500}
  height={300}
/>

Press Enter to start editing

Composed Charts

To combine different Charts, like Lines with Bars, you can use composition with the ChartContainer wrapper.

Inside this wrapper, render either axis components, such as XAxis and YAxis, or any plot component like BarPlot, LinePlot, AreaPlot, and ScatterPlot.

Visit the Composition page for more details.

Positions

Charts are composed of two main areas. The SVG defined by its width and height delimits the available space.

Within this SVG, a dedicated "drawing area" (aka "plot area") serves as the canvas for data representation. Here, elements like lines, bars, and areas visually depict the information. It's controlled by the margin = {top, bottom, left, right} object defining the margin between the SVG and the drawing area.

The space left by margins can display axes, titles, a legend, or any other additional information.

For more information about the position configuration, visit the styling page.

Axis management

MUI X Charts have a flexible approach to axis management, supporting multiple-axis charts with any combination of scales and ranges.

Visit the Axis page for more details.

Styling

MUI X Charts follows the Material UI styling and features all of the customization tools you'd find there, making tweaking charts as straightforward as designing buttons.

Visit the Styling page for more details.