# 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:

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

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


## Sections

Use `sections` to split the arc into threshold bands. Each section ends at its `value`, the last section should end at `max`.
With `sections`, the whole arc is colored, use the [target marker](#target-marker) to show where the value falls:

```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

Set `target` to draw a line marker across the arc at the given value.
Use `targetColor` and `targetSize` to change its color and 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` set the span of the arc in degrees. `0` is the top of the chart, positive values go clockwise:

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

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


A span of 360 degrees renders a full circle. Set `endAngle` lower than `startAngle`
to draw the arc counter-clockwise:

```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` sets the width of the arc, `size` sets the width of the chart. The height follows the arc proportions:

```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>
  );
}
```


## Value formatter

Use `valueFormatter` to format the value in the center label. Screen readers announce the same formatted value:

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

function Demo() {
  return <GaugeChart value={72.456} valueFormatter={(value) => `${value.toFixed(1)}%`} />;
}
```


## Custom label

Use `label` prop to replace the center label with any React node:

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

function Demo() {
  return (
    <GaugeChart
      value={72}
      aria-label="CPU usage"
      label={
        <div>
          <Text ta="center" fz="xl" fw="var(--mantine-font-weight-medium)" c="bright">
            72%
          </Text>
          <Text ta="center" size="sm">
            CPU Usage
          </Text>
        </div>
      }
    />
  );
}
```


## Round caps

Set `roundCaps` to round the endpoints of the arc:

```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} />
      <GaugeChart
        value={72}
        roundCaps
        size={160}
        sections={[
          { value: 60, color: 'teal' },
          { value: 80, color: 'yellow' },
          { value: 100, color: 'red' },
        ]}
      />
    </Group>
  );
}
```


## Accessibility

Set `aria-label` to name the metric, even when the chart has a visible `label`:

```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 | 120 | 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 | 100 | Maximum value of the gauge, |
| min | number | 0 | Minimum value of the gauge. If `min` is greater than `max`, the two are swapped, |
| roundCaps | boolean | false | Whether to round arc endpoints. With `sections`, only the outer ends of the first and last sections are rounded. |
| 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 | 200 | Chart width in px, the height is derived from the arc proportions, |
| startAngle | number | -120 | 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 | 2 | Thickness of the target marker, |
| thickness | number | 12 | 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 | (v) => String(v) | Formats the value in the default label and `aria-valuetext`, |


#### 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 | Threshold section arc, or the value arc when `sections` is not set |
| sectionCap | .mantine-GaugeChart-sectionCap | Round-capped copy of the first and last sections, rendered when roundCaps is set |
| needle | .mantine-GaugeChart-needle | Target marker line (`target` prop) |
| 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 |
