# Scatter Chart (/docs/charts/components/scatter)

Use a scatter chart to show how two numeric measures relate, like latency and acceptance, and to compare a few groups of points on the same axes.

<Example caption="Hover a point, or focus the chart and press the arrow keys, to see its values.">
<Basic />

```tsx
"use client";

import { ScatterChart, type SeriesConfig } from "@kind-ui/charts";

const weekday = [
  { task: "Search", latency: 28, acceptance: 84 },
  { task: "Draft", latency: 52, acceptance: 92 },
  { task: "Summarize", latency: 41, acceptance: 89 },
  { task: "Translate", latency: 65, acceptance: 95 },
];
const weekend = [
  { task: "Search", latency: 35, acceptance: 80 },
  { task: "Draft", latency: 61, acceptance: 88 },
  { task: "Summarize", latency: 47, acceptance: 86 },
  { task: "Translate", latency: 76, acceptance: 93 },
];

const config = {
  weekday: { label: "Weekday", color: "#733bff", legendShape: "circle" },
  weekend: { label: "Weekend", color: "#0f8b8d", legendShape: "diamond" },
} satisfies SeriesConfig;

export default function LatencyChart() {
  return (
    <ScatterChart
      config={config}
      height={280}
      margin={{ top: 8, right: 16 }}
      aria-label="Task latency in milliseconds against acceptance rate, weekday and weekend"
    >
      <ScatterChart.Grid />
      <ScatterChart.XAxis dataKey="latency" name="Latency" unit=" ms" domain={[0, 100]} />
      <ScatterChart.YAxis
        dataKey="acceptance"
        name="Acceptance"
        unit="%"
        domain={[70, 100]}
        ticks={[70, 80, 90, 100]}
        width={48}
      />
      <ScatterChart.Series seriesKey="weekday" data={weekday} shape="circle" />
      <ScatterChart.Series seriesKey="weekend" data={weekend} shape="diamond" />
      <ScatterChart.Tooltip<(typeof weekday)[number]> pointLabel={(row) => row.task} />
      <ScatterChart.Legend />
    </ScatterChart>
  );
}
```
</Example>

## Installation [#installation]

```bash tab="shadcn"
npx shadcn@latest add @kind-ui/scatter-chart
```

```bash tab="npm"
npm install @kind-ui/charts motion recharts
```

## Composition [#composition]

```text
ScatterChart
├── ScatterChart.Background
├── ScatterChart.Grid
├── ScatterChart.XAxis
├── ScatterChart.YAxis
├── ScatterChart.ZAxis
├── ScatterChart.Series
├── ScatterChart.Tooltip
├── ScatterChart.Legend
└── ScatterChart.Content
```

`ScatterChart` holds the series config and the accessible name, and draws only the parts you add. Unlike the other cartesian charts, each `ScatterChart.Series` takes its own `data`. The tooltip and legend read their labels and colors from `config`. `ScatterChart.Content` places your own HTML next to the legend.

## Usage [#usage]

### Series and Axes [#series-and-axes]

Both axes are numeric. Give each one the `dataKey` it reads from the points; `name` and `unit` label the value in the tooltip.

Add one `ScatterChart.Series` per group, with its points in `data` and its `config` key in `seriesKey`. Set `shape` to tell groups apart without color: `circle` (the default), `cross`, `diamond`, `square`, `star`, `triangle` or `wye`. Give the `config` entry the same `legendShape` so the legend matches.

Set `material="clay"` or `"glow"` on a series for a finish on the built-in shapes; see [Materials](../guides/materials.mdx).

`ScatterChart.Tooltip` titles each point with its series label. Pass `pointLabel` to title it from the point's own record instead, like the task name above.

### Bubble Size [#bubble-size]

Add `ScatterChart.ZAxis` to size each point by a third measure. Its `range` sets the smallest and largest bubble area, in square pixels:

<Example caption="Bubble area shows requests. Hover Classify or Extract to see a zero and a missing value.">
<Bubble />

```tsx
"use client";

import { ScatterChart, type SeriesConfig } from "@kind-ui/charts";

const data = [
  { task: "Search", latency: 28, acceptance: 84, requests: 260 },
  { task: "Draft", latency: 52, acceptance: 92, requests: 180 },
  { task: "Summarize", latency: 41, acceptance: 89, requests: 120 },
  { task: "Translate", latency: 65, acceptance: 95, requests: 75 },
  { task: "Classify", latency: 19, acceptance: 81, requests: 0 },
  { task: "Extract", latency: 73, acceptance: 88, requests: null },
];

const config = {
  tasks: { label: "Tasks", color: "#733bff" },
} satisfies SeriesConfig;

export default function RequestsChart() {
  return (
    <ScatterChart
      config={config}
      height={280}
      margin={{ top: 8, right: 16 }}
      aria-label="Task latency, acceptance rate and requests in thousands"
    >
      <ScatterChart.Grid />
      <ScatterChart.XAxis dataKey="latency" name="Latency" unit=" ms" domain={[0, 100]} />
      <ScatterChart.YAxis
        dataKey="acceptance"
        name="Acceptance"
        unit="%"
        domain={[70, 100]}
        ticks={[70, 80, 90, 100]}
        width={48}
      />
      <ScatterChart.ZAxis
        dataKey="requests"
        name="Requests"
        unit="k"
        domain={[0, 300]}
        range={[48, 1000]}
      />
      <ScatterChart.Series seriesKey="tasks" data={data} fillOpacity={0.72} />
      <ScatterChart.Tooltip<(typeof data)[number]>
        pointLabel={(row) => row.task}
        zDimension={{ dataKey: "requests", name: "Requests", unit: "k" }}
      />
    </ScatterChart>
  );
}
```
</Example>

Recharts draws zero and missing sizes at the smallest area and leaves them out of the tooltip. Pass the same key to the tooltip's `zDimension` to show them, as `0k` and `missingValue` ("No data" by default).

### Legend and Keyboard [#legend-and-keyboard]

Pressing a legend item highlights its points and dims the others. Press it again, or press Escape, to clear it. To hide and show series from the legend instead, see [Legend](../building-blocks/legend.mdx).

Focus the chart and press the left and right arrow keys to move through the points of the first series, which shows the tooltip, and Escape to dismiss it. Hover reaches every series.

### Motion [#motion]

Pass `animate` to fade the points in when the chart mounts, or `animate={{ revealDurationMs: 900 }}` to change the duration. Scatter charts don't animate by default. When the reader prefers reduced motion, points appear without fading in. See [Motion](../guides/motion.mdx).

### Loading [#loading]

Set `loading` while the data is on its way. The chart keeps its size and shows placeholder points, which hold still when the reader prefers reduced motion. Screen readers hear `loadingLabel` ("Loading chart" by default):

```tsx
<ScatterChart loading={isPending} loadingLabel="Loading latency" {...props}>
```

## API Reference [#api-reference]

### ScatterChart [#scatterchart]

### ScatterChartOptions

| Prop                     | Type                                                                                                                                                                                                                                                 | Description                                                                                                            |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `visibleSeries?`         | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show, when you control visibility.                                                                  |
| `defaultVisibleSeries?`  | `readonly string[] \| undefined`                                                                                                                                                                                                                     | The series keys to show first, when the chart controls visibility.                                                     |
| `onVisibleSeriesChange?` | `((next: string[]) => void) \| ((next: string[]) => void) \| undefined`                                                                                                                                                                              | Called with the next visible series keys when the legend hides or shows one.                                           |
| `config`                 | `Readonly<Record<string, { label?: string; color: SeriesColor; pattern?: FillPattern; icon?: React.ComponentType; legendShape?: NonNullable<React.ComponentProps<typeof Symbols>["type"]>; formatValue?: (value: ValueType) => React.ReactNode; }>>` | The label, color and value format of each series, keyed by its `dataKey` or `seriesKey`.                               |
| `emphasis?`              | `"auto" \| "none"`                                                                                                                                                                                                                                   | Dims the other series while one is hovered or focused. `"none"` turns it off. Default: `"auto"`                        |
| `interaction?`           | `ChartInteractionConfig \| undefined`                                                                                                                                                                                                                | What pressing a legend item does: highlight a series (the default) or hide and show it.                                |
| `aria-label?`            | `string \| undefined`                                                                                                                                                                                                                                | The chart's accessible name. Pass this or `aria-labelledby`.                                                           |
| `aria-labelledby?`       | `string \| undefined`                                                                                                                                                                                                                                | The id of an element that names the chart. Pass this or `aria-label`.                                                  |
| `legendPosition?`        | `"bottom" \| "top"`                                                                                                                                                                                                                                  | Places the legend and other HTML parts above or below the plot. Default: `"bottom"`                                    |
| `frameProps?`            | `` (Omit<ChartProviderProps, "children" \| "config" \| "defaultVisibleSeries" \| "emphasis" \| "interaction" \| "nonce" \| "onVisibleSeriesChange" \| "visibleSeries"> & { [key: `data-${string}`]: unknown; }) \| undefined ``                      | Attributes, handlers and ref for the outer HTML frame. Plot props remain on the chart.                                 |
| `animate?`               | `boolean \| BaseAnimation \| undefined`                                                                                                                                                                                                              | Fades the points in on mount. Pass options to change the duration or easing. Reduced motion skips it. Default: `false` |
| `loading?`               | `boolean \| undefined`                                                                                                                                                                                                                               | Shows a placeholder plot and hides the legend and tooltip while the data is on its way.                                |
| `loadingLabel?`          | `string \| undefined`                                                                                                                                                                                                                                | What screen readers hear while `loading` is on. Default: `"Loading chart"`                                             |

### ScatterChart.Series [#scatterchartseries]

### ScatterSeriesOptions

| Prop         | Type                          | Description                                                                                                                      |
| ------------ | ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `seriesKey?` | `string \| undefined`         | The `config` key for this series' label, color and visibility. Scatter `dataKey`s name axis values, so set this on every series. |
| `material?`  | `"clay" \| "glow" \| "plain"` | A finish for the built-in symbols. Custom shapes and filters are left as they are.                                               |

### ScatterChart.Tooltip [#scattercharttooltip]

### ScatterTooltipOptions

| Prop            | Type                                            | Description                                                                                                    |
| --------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `pointLabel?`   | `((record: unknown) => ReactNode) \| undefined` | The tooltip title for a point. Receives the point's data record. Default: `` the series label from `config` `` |
| `zDimension?`   | `ScatterSizeDimension<unknown> \| undefined`    | Shows the bubble-size value, including zero and missing values Recharts leaves out.                            |
| `missingValue?` | `ReactNode`                                     | What the tooltip shows for a missing `zDimension` value. Default: `"No data"`                                  |

<Caption>
`ScatterChart`, `ScatterChart.Series` and `ScatterChart.ZAxis` also take every prop of Recharts' [ScatterChart](https://recharts.github.io/en-US/api/ScatterChart/), [Scatter](https://recharts.github.io/en-US/api/Scatter/) and [ZAxis](https://recharts.github.io/en-US/api/ZAxis/), like `margin`, `data`, `shape` and `range`.
</Caption>