# GaugeChart
Package: @mantine/charts
Import: import { GaugeChart } from '@mantine/charts';
Description: Radial gauge chart for KPI and status display

## Usage

`GaugeChart` displays a single value on a radial arc – use it for KPIs, utilization
and status indicators. The arc is filled from `min` (`0` by default) up to `value`,
and the value is displayed in the center of the chart.

Unlike most charts in `@mantine/charts`, `GaugeChart` does not use
[recharts](https://recharts.org/) – it is rendered as a plain `svg` element.

```tsx
import { GaugeChart } from '@mantine/charts';

function Demo() {
  return <GaugeChart value={72} size={200} thickness={12} />;
}
```


## Sections

`sections` splits the arc into threshold bands. Each section is filled from the upper
bound of the previous section up to its own `value`, so the last section should end
at `max`. Sections are sorted by `value` automatically.

Note that when `sections` is set, the arc represents the thresholds rather than the
current value: the entire arc is colored and `value` is displayed only in the center
label. To mark where the value falls on the arc, use the [target marker](#target-marker):

```tsx
// Demo.tsx
import { GaugeChart } from '@mantine/charts';
import { sections } from './data';

function Demo() {
  return <GaugeChart value={72} sections={sections} />;
}

// data.ts
import { GaugeChartSection } from '@mantine/charts';

export const sections: GaugeChartSection[] = [
  { value: 60, color: 'teal' },
  { value: 80, color: 'yellow' },
  { value: 100, color: 'red' },
];
```


## Target marker

`target` draws a line marker across the arc at the given value. Use it to display a goal
next to the current value, or to point at the current value on a gauge with `sections`.
`targetColor` controls its color and `targetSize` its thickness:

```tsx
// Demo.tsx
import { GaugeChart } from '@mantine/charts';
import { sections } from './data';

function Demo() {
  return <GaugeChart value={72} target={75} sections={sections} />;
}

// data.ts
import { GaugeChartSection } from '@mantine/charts';

export const sections: GaugeChartSection[] = [
  { value: 60, color: 'teal' },
  { value: 80, color: 'yellow' },
  { value: 100, color: 'red' },
];
```


## Start and end angle

`startAngle` and `endAngle` control the span of the arc in degrees, `-120` and `120` by
default (`0` is the top of the chart, positive values go clockwise). The `viewBox` of the
chart is calculated from the resulting arc, so an arc that spans only a part of the circle
does not leave empty space around the chart:

```tsx
import { GaugeChart } from '@mantine/charts';

function Demo() {
  return <GaugeChart value={72} startAngle={-90} endAngle={90} />;
}
```


A span of 360 degrees or more renders a full circle, and setting `endAngle` lower than
`startAngle` sweeps the arc counter-clockwise – `sections` and `target` follow the same
direction:

```tsx
import { GaugeChart } from '@mantine/charts';

function Demo() {
  return (
    <>
      {/* Full circle */}
      <GaugeChart value={72} startAngle={0} endAngle={360} />

      {/* Counter-clockwise */}
      <GaugeChart value={72} startAngle={120} endAngle={-120} />
    </>
  );
}
```

## Thickness

`thickness` controls the width of the arc in px, `size` controls both the width and the
height of the chart:

```tsx
import { GaugeChart } from '@mantine/charts';
import { Group } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <GaugeChart value={72} thickness={6} size={160} />
      <GaugeChart value={72} thickness={20} size={160} />
    </Group>
  );
}
```


## Custom label

By default, the center label displays `value` formatted with `valueFormatter`. Use the
`label` prop to render any React node instead:

```tsx
import { GaugeChart } from '@mantine/charts';
import { Text } from '@mantine/core';

function Demo() {
  return (
    <GaugeChart
      value={72}
      label={
        <div>
          <Text ta="center" fz="xl" fw={700}>72%</Text>
          <Text ta="center" fz="xs" c="dimmed">CPU Usage</Text>
        </div>
      }
    />
  );
}
```


## Round caps

Set `roundCaps` to round the endpoints of the arc. Round caps are not applied to
`sections` – rounded caps of adjacent sections would overlap each other:

```tsx
import { GaugeChart } from '@mantine/charts';
import { Group } from '@mantine/core';

function Demo() {
  return (
    <Group>
      <GaugeChart value={72} roundCaps size={160} />
      <GaugeChart value={72} roundCaps={false} size={160} />
    </Group>
  );
}
```


## Accessibility

The root `svg` element has `role="meter"` with `aria-valuenow`, `aria-valuemin`,
`aria-valuemax` and `aria-valuetext` attributes. Set `aria-label` to give the gauge
an accessible name:

```tsx
import { GaugeChart } from '@mantine/charts';

function Demo() {
  return <GaugeChart value={72} aria-label="CPU utilization" />;
}
```


#### Props

**GaugeChart props**

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| endAngle | number | - | End angle in degrees, |
| filledColor | MantineColor | - | Color of the filled arc when sections are not provided |
| label | React.ReactNode | - | Label displayed in the center of the gauge |
| max | number | - | Maximum value of the gauge, |
| min | number | - | Minimum value of the gauge, |
| roundCaps | boolean | - | Whether to round arc endpoints. Not applied to `sections` – rounded caps of adjacent sections would overlap each other. |
| sections | GaugeChartSection[] | - | Threshold sections of the gauge arc, each section is filled from the previous section upper bound to its own `value`. If set, the arc is not filled based on `value`. |
| size | number | - | Chart size (width and height), |
| startAngle | number | - | Start angle in degrees, |
| target | number | - | Value marked on the arc with a line marker, use to display a goal or the current value of a gauge with `sections` |
| targetColor | MantineColor | - | Color of the target marker |
| targetSize | number | - | Thickness of the target marker, |
| thickness | number | - | Arc thickness in px, |
| trackColor | MantineColor | - | Color of the gauge track (unfilled portion) |
| value | number | required | Current value to display. Fills the arc from `min` up to `value`, unless `sections` is set – then the arc is colored by thresholds and the value is displayed only in the center label. |
| valueFormatter | (value: number) => string | - | Value formatter for default label, |


#### Styles API

GaugeChart component supports Styles API. With Styles API, you can customize styles of any inner element. Follow the documentation to learn how to use CSS modules, CSS variables and inline styles to get full control over component styles.

**GaugeChart selectors**

| Selector | Static selector | Description |
|----------|----------------|-------------|
| root | .mantine-GaugeChart-root | Root SVG element |
| track | .mantine-GaugeChart-track | Background arc path |
| section | .mantine-GaugeChart-section | Filled section arc path |
| needle | .mantine-GaugeChart-needle | Target marker line |
| label | .mantine-GaugeChart-label | Center label container |

**GaugeChart CSS variables**

| Selector | Variable | Description |
|----------|----------|-------------|
| root | --gauge-size | Controls chart width, height is derived from the arc proportions |