Charts - Gauge

Use gauge charts to show a numeric value within a defined range as an arc or meter.

Overview

A gauge shows a numeric value within a defined range, often as an arc or needle against a scale. Use it for metrics like progress, capacity, or levels (for example, battery, storage, or completion).

The demo below shows basic gauge configurations.

import Stack from '@mui/material/Stack';
import { Gauge } from '@mui/x-charts/Gauge';

export default function BasicGauges() {
  return (
    <Stack direction={{ xs: 'column', md: 'row' }} spacing={{ xs: 1, md: 3 }}>
      <Gauge width={100} height={100} value={60} />
      <Gauge width={100} height={100} value={60} startAngle={-90} endAngle={90} />
    </Stack>
  );
}

Basics

Pass the current value with the value prop. By default, the scale runs from 0 through 100. Use valueMin and valueMax to set a different range.

import Stack from '@mui/material/Stack';
import { Gauge } from '@mui/x-charts/Gauge';

export default function GaugeValueRange() {
  return (
    <Stack direction={{ xs: 'column', md: 'row' }} spacing={{ xs: 1, md: 3 }}>
      <Gauge width={100} height={100} value={50} />
      <Gauge width={100} height={100} value={50} valueMin={10} valueMax={60} />
    </Stack>
  );
}

Arc configuration

Use these props to change the arc shape:

startAngle and endAngle: angle range in degrees
innerRadius and outerRadius: arc radii, as a pixel value or a percentage string (such as '50%')
cornerRadius: corner rounding, as a pixel value or percentage string

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

<Gauge
  value={75}
  startAngle={0}
  endAngle={360}
  innerRadius="80%"
  outerRadius="100%"
  // ...
/>

Playground

value

startAngle

endAngle

innerRadius

outerRadius

The gauge shows the value in the center of the arc by default. Use the text prop to customize the center text. Pass a string or a formatter function. The formatter receives an object with value, valueMin, and valueMax.

Use the gaugeClasses.valueText class to change the text layout.

import { Gauge, gaugeClasses } from '@mui/x-charts/Gauge';

<Gauge
  value={75}
  startAngle={-110}
  endAngle={110}
  sx={{
    [& .MuiGauge-valueText]: {
      fontSize: 40,
      transform: 'translate(0px, 0px)',
    },
  }}
  text={({ value, valueMax }) => `${value} / ${valueMax}`}
/>

Playground

value

fontSize

Arc design

Use the gaugeClasses export for class names that target different parts of the gauge, such as valueText, valueArc, and referenceArc.

See Gauge—Classes for the full list.

import { Gauge, gaugeClasses } from '@mui/x-charts/Gauge';

const settings = {
  width: 200,
  height: 200,
  value: 60,
};

export default function ArcDesign() {
  return (
    <Gauge
      {...settings}
      cornerRadius="50%"
      sx={(theme) => ({
        [`& .${gaugeClasses.valueText}`]: {
          fontSize: 40,
        },
        [`& .${gaugeClasses.valueArc}`]: {
          fill: '#52b202',
        },
        [`& .${gaugeClasses.referenceArc}`]: {
          fill: theme.palette.text.disabled,
        },
      })}
    />
  );
}

Adding elements

Using the default Gauge

Add elements as children of Gauge to render them on top of the default arc and text.

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

<Gauge value={25} valueMax={50}>
  <AddedElement />
</Gauge>;

Using the Gauge container

Use GaugeContainer and the following components when you need more control over the layout:

GaugeReferenceArc: the reference arc
GaugeValueArc: the value arc
GaugeValueText: the text in the center

import {
  GaugeContainer,
  Gauge,
  GaugeReferenceArc,
  GaugeValueArc,
} from '@mui/x-charts/Gauge';

<GaugeContainer value={25} valueMax={50}>
  <GaugeReferenceArc />
  <GaugeValueArc />
  <AddedElement />
</GaugeContainer>;

Creating custom components

Use the useGaugeState() hook to build custom gauge components. It returns:

Value info: value, valueMin, valueMax
Arc geometry: startAngle, endAngle, outerRadius, innerRadius, cornerRadius, cx, cy
Computed: maxRadius (largest radius that fits the drawing area) and valueAngle (angle for the current value)

import {
  GaugeContainer,
  GaugeValueArc,
  GaugeReferenceArc,
  useGaugeState,
} from '@mui/x-charts/Gauge';

function GaugePointer() {
  const { valueAngle, outerRadius, cx, cy } = useGaugeState();

  if (valueAngle === null) {
    // No value to display
    return null;
  }

  const target = {
    x: cx + outerRadius * Math.sin(valueAngle),
    y: cy - outerRadius * Math.cos(valueAngle),
  };
  return (
    <g>
      <circle cx={cx} cy={cy} r={5} fill="red" />
      <path
        d={`M ${cx} ${cy} L ${target.x} ${target.y}`}
        stroke="red"
        strokeWidth={3}
      />
    </g>
  );
}

export default function CompositionExample() {
  return (
    <GaugeContainer
      width={200}
      height={200}
      startAngle={-110}
      endAngle={110}
      value={30}
    >
      <GaugeReferenceArc />
      <GaugeValueArc />
      <GaugePointer />
    </GaugeContainer>
  );
}

Accessibility

The gauge follows the Meter ARIA pattern. The container has the meter role, and aria-valuenow, aria-valuemin, and aria-valuemax match the value range.

Label

If the gauge has a visible label, set aria-labelledby to point to it. Otherwise, provide a label with aria-label.

Presentation

Assistive technologies often present the value as a percentage. You can override this by setting the aria-valuetext attribute.

For example, a battery level indicator is clearer when it announces a duration (such as hours remaining) instead of only a percentage.

<h3 id="battery_level_label">
  Battery level
</h3>
<Gauge
  value={6}
  valueMax={12}
  aria-labelledby="battery_level_label"
  aria-valuetext="50% (6 hours) remaining"
/>

Composition

Use GaugeContainer to supply the gauge parameters: value, valueMin, valueMax, startAngle, endAngle, and so on.

In addition to the shared chart components available for composition, you can use:

GaugeReferenceArc: the reference arc
GaugeValueArc: the value arc
GaugeValueText: the text in the center

Here's how the gauge is composed:

<GaugeContainer>
  <GaugeReferenceArc />
  <GaugeValueArc skipAnimation={skipAnimation} />
  <GaugeValueText text={text} />
</GaugeContainer>

API

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