<!-- Protocore Design System — ScatterChart -->
# ScatterChart

- **Category:** Charts (`charts`)
- **Slug:** `charts/scatter-chart`
- **Status:** stable
- **Platforms:** web
- **Import:** `import { ScatterChart } from "@protocore/pds/charts";`
- **Docs:** https://pds.protocore.io/components/charts/scatter-chart

> A monochrome-plus-signal scatter plot with sharp square marks over the shared --pds-chart-N ramp, recharts-backed.

## Import path

`ScatterChart` ships from the **`@protocore/pds/charts`** subpath — not the main entry — so recharts stays out of the core bundle. `recharts` (>=3) is an **optional peer**; install it in apps that render charts.

```tsx
import { ScatterChart } from "@protocore/pds/charts";
import { ChartContainer } from "@protocore/pds";
```

## When to use it

Use **ScatterChart** to show the *correlation* between two numeric measures across many observations — latency vs error rate, size vs cost. Add a third (size) dimension with [BubbleChart](/charts/bubble-chart); for a value over an ordered axis use [LineChart](/charts/line-chart).

Keep the lead series on the ink `chart-1` slot and let others recede. Every prop beyond `data`/`series`/`xKey`/`height` is forwarded to the underlying recharts `<ScatterChart>`.

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `data` | `ReadonlyArray<Record<string, string \| number \| null \| undefined>>` | yes | — | Row-oriented data; each datum keyed by `xKey` and by every series `key` (its y value). |
| `series` | `ChartSeries[]` | yes | — | Series to plot, in draw + legend order. `ChartSeries` = `{ key: string; label?: string; color?: string }` — each `key` is the datum's y value; color defaults to `--pds-chart-N` by position. |
| `xKey` | `string` | yes | — | Datum key for the numeric x-axis value. |
| `height` | `number` | no | `240` | Chart height in px. |
| `...rest` | `Omit<RechartsScatterChartProps, 'data' \| 'children' \| 'width' \| 'height' \| 'ref'>` | no | — | Remaining props spread onto the underlying recharts `<ScatterChart>`. |

## Examples

### Basics

Give it `data`, a numeric `xKey`, and one or more `series` (each `key` is the y value). Both axes are numeric; marks are sharp squares coloured from the ramp. Wrap it in a [ChartContainer](/charts/chart-container) for the frame and the ramp.

```tsx
import { ChartContainer } from "@protocore/pds";
import { ScatterChart } from "@protocore/pds/charts";

const data = [
  { size: 2, latency: 120 },
  { size: 3, latency: 98 },
  { size: 5, latency: 160 },
  { size: 6, latency: 140 },
  { size: 8, latency: 210 },
  { size: 10, latency: 185 },
  { size: 13, latency: 240 },
];

export default function Demo() {
  return (
    <ChartContainer label="Latency vs payload size" height={240}>
      <ScatterChart data={data} xKey="size" series={[{ key: "latency", label: "p95 latency / ms" }]} />
    </ChartContainer>
  );
}
```

## Do & don't

**Do**

- Wrap it in a ChartContainer so it inherits the `--pds-chart-*` ramp.
- Give each series a human `label` for the tooltip and legend.
- Reserve a signal hue for the series that carries meaning.
- Use numeric x and y values — both axes are quantitative.

**Don't**

- Don't plot ordered categories on the x-axis — use a LineChart or BarChart.
- Don't import it from `@protocore/pds`; it lives on the `/charts` subpath.
- Don't give every series a bright colour — the ramp ranks by luminance.
- Don't add a size dimension by hand — use BubbleChart's `zKey`.

## Accessibility

**Notes**

- recharts renders the plot as SVG; provide surrounding context (a ChartContainer `label`, a caption, or a data table) for assistive tech.
- Series stay distinguishable by luminance, not hue alone, thanks to the monochrome ramp; pair multi-series plots with a legend.

## Related

`bubble-chart`, `line-chart`, `chart-container`

---

© Protocore. All rights reserved. Use of the Protocore Design System requires prior written authorization from Protocore (contact@protocore.io). These machine-readable materials must not be ingested into ML-training datasets or derivative design systems. See https://pds.protocore.io/legal/