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.
Installation
npx shadcn@latest add @minidev/scatter-chart
MiniDev UI is in the shadcn registry directory, so the short form works with no setup. Older CLI versions can use the full URL: npx shadcn@latest add https://ui.minidev.pro/r/scatter-chart.json
Usage
import { ScatterChart } from "@/components/ui/scatter-chart"
export function Example() {
return (
<ScatterChart />
)
}
API reference
| Prop | Type | Default |
|---|---|---|
| seriesOne or more series of `{ x, y, size?, label? }` points. | ScatterSeries[] | SAMPLE |
| xLabelX axis title, also used in the tooltip and point labels. | string | - |
| yLabelY axis title, also used in the tooltip and point labels. | string | - |
| xFormatIntl.NumberFormat options (works from Server Components) or a function, for x ticks and values. | Format | - |
| yFormatIntl.NumberFormat options or a function, for y ticks and values. | Format | - |
| sizeLabelWhat `size` measures, shown in the tooltip in bubble mode. | string | "Size" |
| sizeRangeSmallest and largest bubble diameter in px. Bubble area grows with `size`. | [number, number] | [8, 40] |
| referenceLinesDashed lines at fixed values, such as a target or a median. Included in the axis range. | ReferenceLine[] | [] |
| heightPlot height in px, not counting the axis labels and legend. | number | 280 |
| localeLocale for number formatting. Fixed by default so server and browser render the same text. | string | "en-US" |
| legendShow a ChartLegend under the chart when there is more than one series. | boolean | true |
| labelAccessible name of the chart. | string | "Scatter chart" |
| className | string | - |
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.
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. |
| ArrowRightorArrowDown | Moves to the next point in x order and shows its crosshair and tooltip. |
| ArrowLeftorArrowUp | Moves to the previous point in x order. |
| HomeorEnd | Jumps to the first or last point. |
Accessibility
- The plot is a
role="group"named fromlabelplus 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.
Frequently asked questions
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.
Dependencies
npm
Built from
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.
Bubble chart
Give points a size and the chart switches to bubbles whose area tracks the value. sizeLabel names it in the tooltip.
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.