# Scatter chart

> The relationship between two measurements across many runs, with limits, a fit line and one point called out.

Category: Charts · Atomic level: organism
Page: https://ui.dtheo.dev/docs/charts/scatter-chart

## Install

```bash
npx dtheo@latest add scatter-chart
# or, with the shadcn CLI
npx shadcn@latest add https://ui.dtheo.dev/r/scatter-chart.json
```

Dependencies: d3-scale. Registry dependencies: none.

## Exports

`ScatterChart`

## Use it for

- Gain against overshoot, temperature against current, any two measures per run
- Spotting outliers

## Reach for something else

- A measure over time: use Line chart
- One measure’s spread: use Histogram
- More than three groups: facet into several charts

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `points` | `ScatterPoint[]` | – | `{ x, y, group?, label? }` for every point. |
| `groups` | `ScatterGroup[]` | – | Up to three groups with label and tone. The first listed draws on top. |
| `limits` | `ScatterLimit[]` | – | Limit lines on either axis; the out-of-spec side gets a faint wash. |
| `highlight` | `string` | – | The label of a point to call out. |
| `fit` | `boolean` | `false` | Draw a least-squares line and its r². |

## Keyboard

| Keys | Action |
| --- | --- |
| Arrow left / right | Move to the next point, left to right |
| Shift + arrow | Skip a tenth of the points |
| Home / End | Jump to the first or last point |
| Escape | Clear the readout |

## Accessibility

- Points draw on a canvas, so thousands stay fast; the active point is announced in words.
- Groups carry a label and a count in the legend, never color alone.

## Examples

### scatter-chart

```tsx
import { ScatterChart } from '@/components/charts/scatter-chart';
// Synthetic demo data: npx dtheo add lab-data, or pass your own.
import { OVERSHOOT_USL, runs } from '@/lib/lab-data';

const points = runs.map((r) => ({
  x: r.kp,
  y: r.overshoot,
  label: r.id,
  group: r.overshoot > OVERSHOOT_USL ? 'fail' : 'pass',
}));

export default function ScatterChartExample() {
  return (
    <div className="flex w-full flex-col gap-3">
      <div className="flex flex-col">
        <span className="text-headline">Gain against overshoot</span>
        <span className="text-caption text-muted-foreground">RA-14 hip pitch · {runs.length} step tests</span>
      </div>
      <ScatterChart
        points={points}
        groups={[
          { id: 'fail', label: 'Over limit', tone: 'critical' },
          { id: 'pass', label: 'Within limit', tone: 'muted' },
        ]}
        xDomain={[1.5, 4.75]}
        yDomain={[0, 20]}
        xLabel="Kp"
        yLabel="Overshoot"
        yUnit="%"
        limits={[{ axis: 'y', value: OVERSHOOT_USL, label: 'Limit 10 %' }]}
        highlight="R-0412"
        fit
        height={280}
        ariaLabel={`Overshoot rises with Kp across ${runs.length} runs. Every run over the 10 % limit has Kp above 3.1; R-0412, at Kp 4.20, overshoots 17.6 %.`}
      />
    </div>
  );
}
```

## Used in

- Loop tuning (page): https://ui.dtheo.dev/examples/tuning
