# Scatter Chart

> React scatter and bubble chart in plain SVG with rounded axis ticks, reference lines, hover that snaps to the nearest point and arrow-key point navigation.

- Kind: Component (Charts)
- Docs: https://ui.minidev.pro/docs/scatter-chart
- Source (registry JSON with the full file): https://ui.minidev.pro/r/scatter-chart.json
- License: MIT. One file, yours to edit after install.

## When to use

Use it to show how two measures relate across many items: deal size against win rate, price against rating, latency against payload. Give points a `size` and it becomes a bubble chart. For one measure over time use LineChart or InteractiveAreaChart; for totals by category use BarChart. No chart library: ticks are rounded to 1, 2, 2.5 or 5 steps, and hovering a ChartLegend entry dims the other series.

## Installation

### shadcn CLI (copies the source into your project)

```bash
npx shadcn@latest add @minidev/scatter-chart
```

Writes `components/ui/scatter-chart.tsx` plus the MiniDev files it is built from (chart-legend, chart-tooltip-card) and installs its npm dependencies. Older CLI versions: `npx shadcn@latest add https://ui.minidev.pro/r/scatter-chart.json`.

### npm package

```bash
npm i minidev-ui-kit motion
```

Add the tokens to your global stylesheet once:

```css
@import "tailwindcss";
@import "minidev-ui-kit/styles.css";
@source "../node_modules/minidev-ui-kit";
```

Next.js also needs `transpilePackages: ["minidev-ui-kit"]` in next.config.

## Import

After the shadcn install:

```tsx
import { ScatterChart } from "@/components/ui/scatter-chart"
```

From the npm package:

```tsx
import { ScatterChart } from "minidev-ui-kit/ui/scatter-chart"
```

## Usage

```tsx
import { ScatterChart } from "@/components/ui/scatter-chart"

export function Example() {
  return (
    <ScatterChart />
  )
}
```

## Props

| Prop | Type | Default | Required | Description |
| --- | --- | --- | --- | --- |
| `series` | `ScatterSeries[]` | `SAMPLE` | no | One or more series of `{ x, y, size?, label? }` points. |
| `xLabel` | `string` | - | no | X axis title, also used in the tooltip and point labels. |
| `yLabel` | `string` | - | no | Y axis title, also used in the tooltip and point labels. |
| `xFormat` | `Format` | - | no | Intl.NumberFormat options (works from Server Components) or a function, for x ticks and values. |
| `yFormat` | `Format` | - | no | Intl.NumberFormat options or a function, for y ticks and values. |
| `sizeLabel` | `string` | `"Size"` | no | What `size` measures, shown in the tooltip in bubble mode. |
| `sizeRange` | `[number, number]` | `[8, 40]` | no | Smallest and largest bubble diameter in px. Bubble area grows with `size`. |
| `referenceLines` | `ReferenceLine[]` | `[]` | no | Dashed lines at fixed values, such as a target or a median. Included in the axis range. |
| `height` | `number` | `280` | no | Plot height in px, not counting the axis labels and legend. |
| `locale` | `string` | `"en-US"` | no | Locale for number formatting. Fixed by default so server and browser render the same text. |
| `legend` | `boolean` | `true` | no | Show a ChartLegend under the chart when there is more than one series. |
| `label` | `string` | `"Scatter chart"` | no | Accessible name of the chart. |
| `className` | `string` | - | no |  |

## Examples

### Deal size against days to close

Two series, a target line on the y axis and compact currency ticks. Hover a legend entry to dim the other series.

```tsx
const pipeline = [
  {
    name: "Inbound",
    points: [
      { x: 8400, y: 14, label: "Juniper Studio" }, { x: 15800, y: 24 }, { x: 26800, y: 33 },
      { x: 31200, y: 29 }, { x: 44200, y: 38 }, { x: 52800, y: 47, label: "Helix Biotech" },
    ],
  },
  {
    name: "Outbound",
    points: [
      { x: 18200, y: 46 }, { x: 33400, y: 61 }, { x: 41800, y: 58 },
      { x: 63800, y: 69, label: "Meridian Freight" }, { x: 72400, y: 88 }, { x: 86600, y: 96, label: "Cobalt Systems" },
    ],
  },
]

<ChartCard title="Pipeline" description="Closed deals, last two quarters">
  <ScatterChart
    label="Deal size against days to close"
    xLabel="Annual contract value"
    yLabel="Days to close"
    xFormat={{ style: "currency", currency: "USD", notation: "compact" }}
    referenceLines={[{ axis: "y", value: 45, label: "Target 45 days" }]}
    series={pipeline}
  />
</ChartCard>
```

### Bubble chart

Give points a size and the chart switches to bubbles whose area tracks the value. sizeLabel names it in the tooltip.

```tsx
<ScatterChart
  label="Plan price against net promoter score"
  xLabel="Price per seat"
  yLabel="NPS"
  sizeLabel="Customers"
  xFormat={{ style: "currency", currency: "USD", maximumFractionDigits: 0 }}
  sizeRange={[10, 48]}
  series={[
    { name: "Starter", color: "chart-3", points: [{ x: 12, y: 31, size: 420, label: "Starter monthly" }, { x: 10, y: 38, size: 610, label: "Starter yearly" }] },
    { name: "Pro", color: "chart-1", points: [{ x: 39, y: 46, size: 1280, label: "Pro monthly" }, { x: 32, y: 52, size: 1760, label: "Pro yearly" }] },
    { name: "Business", color: "chart-2", points: [{ x: 89, y: 58, size: 240, label: "Business monthly" }, { x: 74, y: 63, size: 390, label: "Business yearly" }] },
  ]}
/>
```

### Outliers against a budget

One series with reference lines on both axes. Tab to the chart, then walk the points with the arrow keys to find the slow request.

```tsx
<ScatterChart
  label="Latency against payload size"
  xLabel="Payload"
  yLabel="Latency"
  xFormat={(n) => `${n} KB`}
  yFormat={(n) => `${n} ms`}
  height={220}
  referenceLines={[
    { axis: "y", value: 300, label: "Budget 300 ms" },
    { axis: "x", value: 100, label: "Batch limit" },
  ]}
  series={[{ name: "Sync requests", points: requests }]}
/>
```

## Keyboard interactions

| Key | Action |
| --- | --- |
| `Tab` | Moves focus onto one point: the leftmost at first, then the last point you visited. The whole chart is one tab stop. |
| `ArrowRight` or `ArrowDown` | Moves to the next point in x order and shows its crosshair and tooltip. |
| `ArrowLeft` or `ArrowUp` | Moves to the previous point in x order. |
| `Home` or `End` | Jumps to the first or last point. |

## Accessibility

- The plot is a `role="group"` named from `label` plus the counts, for example "Latency against payload size, 1 series, 20 points".
- Each point is a focusable `role="img"` labelled with its series, point label, axis names and formatted values, for example "Sync requests, Payload 96 KB, Latency 410 ms".
- The tooltip, grid, tick labels and crosshair are `aria-hidden`, because the focused point's label already carries the same values.
- Under reduced motion, points move, appear and leave with `{ duration: 0 }`. Hovering a legend entry dims the other series with a CSS opacity transition, which the kit stylesheet cuts to 0.01ms.

## FAQ

### How do I make a bubble chart?

Give points a `size`: once any point has one, every point is drawn as a bubble, the largest `size` gets the largest diameter in `sizeRange` (`[8, 40]` px by default) and area grows in step with the value. Bigger bubbles are painted first, so small ones stay on top. Set `sizeLabel` to name the value in the tooltip.

### How do I format the axes as currency or percent from a Server Component?

Pass `Intl.NumberFormat` options: `xFormat={{ style: "currency", currency: "USD", notation: "compact" }}`. Options are plain objects, so they can cross from a Server Component; a function such as `(n) => n + " ms"` works only from client code. Numbers use `locale`, `"en-US"` by default, so server and browser render the same text.

### How are the axis ranges chosen?

They fit the data. Each axis spans the smallest and largest value of all points and reference lines, widened to round ticks on a 1, 2, 2.5 or 5 step, about five intervals. There is no prop to fix the range, and an axis only starts at zero when the data is near zero.

### Does it need a chart library?

No. It is plain SVG and HTML with no chart dependency. Series colours come from the `--chart-1` to `--chart-5` CSS variables, the same names shadcn themes define, so set those to recolour it.

## Rules for generating code

- Use semantic tokens only (bg, surface, sunken, border, fg, fg-muted, fg-subtle, ink, accent, success, warning, danger). Never raw hex or palette steps like blue-500.
- Shadows only from the set: shadow-xs, shadow-sm, shadow-raised, shadow-md, shadow-lg, shadow-overlay.
- Numbers use tabular-nums. Dark mode is the `dark` class on <html>; components never branch on theme.

## Dependencies

- npm: `motion`
- Built from: [chart-legend](https://ui.minidev.pro/docs/chart-legend/md), [chart-tooltip-card](https://ui.minidev.pro/docs/chart-tooltip-card/md)

## Related

- [Line Chart](https://ui.minidev.pro/docs/line-chart/md): A multi series SVG line chart with smooth curves, a dashed hairline grid and dots on the last point of each line, colored from chart tokens. No library.
- [Interactive Area Chart](https://ui.minidev.pro/docs/interactive-area-chart/md): A React SVG area chart with a crosshair that follows the pointer or arrow keys, showing the value and percent change against a dashed comparison line.
- [Bar Chart](https://ui.minidev.pro/docs/bar-chart/md): Lightweight React bar chart with rounded bars, dashed gridlines and labels. Hovering a bar dims the rest and shows its value; the peak is highlighted first.
- [Chart Legend](https://ui.minidev.pro/docs/chart-legend/md): Wrapping chart legend with small color swatches and labels. Pass colors per series or fall back to accent, success, warning and danger theme tokens.
- [Area Chart](https://ui.minidev.pro/docs/area-chart/md): Dependency free SVG area chart for React with a smoothed line, dashed grid, gradient fill and an optional highlighted point. Strokes stay crisp at any size.
- [Chart Card](https://ui.minidev.pro/docs/chart-card/md): Card wrapper for charts with a title, optional description and a minimum height body. Pairs with the area, bar and donut charts in a React dashboard.

---

All 557 components: https://ui.minidev.pro/llms.txt (full text: https://ui.minidev.pro/llms-full.txt).
