Charts - Bars

Bar charts express quantities through a bar's length, using a common baseline.

Basics

Bar charts series should contain a data property containing an array of values.

You can customize bar ticks with the xAxis. This axis might have scaleType='band' and its data should have the same length as your series.

Using a dataset

If your data is stored in an array of objects, you can use the dataset helper prop. It accepts an array of objects such as dataset={[{x: 1, y: 32}, {x: 2, y: 41}, ...]}.

You can reuse this data when defining the series and axis, thanks to the dataKey property.

For example xAxis={[{ dataKey: 'x'}]} or series={[{ dataKey: 'y'}]}.

Bar size

You can define bar dimensions with categoryGapRatio and barGapRatio properties.

The categoryGapRatio defines the gap between two categories. The ratio is obtained by dividing the size of the gap by the size of the category (the space used by bars).

The barGapRatio defines the gap between two bars of the same category. It's the size of the gap divided by the size of the bar. So a value of 1 will result in a gap between bars equal to the bar width. And a value of -1 will make bars overlap on top of each other.

Stacking

Each bar series can get a stack property expecting a string value. Series with the same stack will be stacked on top of each other.

Stacking strategy

You can use the stackOffset and stackOrder properties to define how the series will be stacked.

By default, they are stacked in the order you defined them, with positive values stacked above 0 and negative values stacked below 0.

For more information, see stacking docs.

Layout

Bar direction

Bar charts can be rendered with a horizontal layout by providing the layout="horizontal" prop. If you're using composition, you should set the property layout: 'horizontal' to each bar series object.

Tick placement

When using a "band" scale, the axis has some additional customization properties about the tick position.

• tickPlacement for the position of ticks
• tickLabelPlacement for the position of the label associated with the tick

You can test all configuration options in the following demo:

Grid

You can add a grid in the background of the chart with the grid prop.

See Axis—Grid documentation for more information.

Color scale

As with other charts, you can modify the series color either directly, or with the color palette.

You can also modify the color by using axes colorMap which maps values to colors. The bar charts use by priority:

1. The value axis color
2. The band axis color
3. The series color

Learn more about the colorMap properties in the Styling docs.

Border Radius

To give your bar chart rounded corners, you can change the value of the borderRadius property on the BarChart.

It works with any positive value and is properly applied to horizontal layouts, stacks, and negative values.

Labels

You can display labels on the bars. To do so, the BarChart or BarPlot accepts a barLabel property. It can either get a function that gets the bar item and some context. Or you can pass 'value' to display the raw value of the bar.

Custom Labels

You can display, change, or hide labels based on conditional logic. To do so, provide a function to the barLabel. Labels are not displayed if the function returns null.

In the example we display a 'High' text on values higher than 10, and hide values when the generated bar height is lower than 60px.

Click event

Bar charts provides two click handlers:

• onItemClick for click on a specific bar.
• onAxisClick for a click anywhere in the chart

They both provide the following signature.

const clickHandler = (
  event, // The mouse event.
  params, // An object that identifies the clicked elements.
) => {};

Composition

If you're using composition, you can get those click event as follows. Notice that the onAxisClick will handle both bar and line series if you mix them.

import ChartsOnAxisClickHandler from '@mui/x-charts/ChartsOnAxisClickHandler';
// ...

<ChartContainer>
  {/* ... */}
  <ChartsOnAxisClickHandler onAxisClick={onAxisClick} />
  <BarPlot onItemClick={onItemClick} />
</ChartContainer>;

Animation

To skip animation at the creation and update of your chart, you can use the skipAnimation prop. When set to true it skips animation powered by @react-spring/web.

Charts containers already use the useReducedMotion from @react-spring/web to skip animation according to user preferences.

// For a single component chart
<BarChart skipAnimation />

// For a composed chart
<ResponsiveChartContainer>
  <BarPlot skipAnimation />
</ResponsiveChartContainer>

API

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

• <BarChart />
• <BarChartPro />
• <BarElement />
• <BarLabel />
• <BarPlot />
• <ChartsGrid />
• <ChartsOnAxisClickHandler />