Scatter Chart
⋯
import { ScatterChart } from "@nesra/ui/scatter-chart";export function ScatterExample() { return ( <ScatterChart title="Content performance" summary="Retention and engagement percentages. Bubble area measures views. These values are synthetic." xAxis={{ label: "Retention", formatValue: (value) => `${value}%` }} yAxis={{ label: "Engagement", formatValue: (value) => `${value}%` }} sizeLabel="Views" data={[ { id: "tutorial", label: "Tutorial", series: "content", x: 42, y: 6, size: 24000 }, { id: "review", label: "Review", series: "content", x: 25, y: 3, size: 11000 }, ]} series={[{ key: "content", label: "Content", color: "blue" }]} referenceLines={[ { axis: "x", value: 30 }, { axis: "y", value: 4, label: "Engagement target" }, ]} /> );}ScatterChart extends the Metrics chart foundation for two numeric coordinates.
Consumers supply observations, group labels, units, and thresholds. The component
owns plotting, axes, hover details, keyboard exploration, and the equivalent data
table. Its colors come from chart tokens, so it follows Light and Dark like the
Metrics charts. Point details use the inverse tooltip
surface. Reference lines use the Figma threshold style: a dashed
stroke-destructive line with a text-destructive label.
Import ScatterChart from @nesra/ui or @nesra/ui/scatter-chart.
Data and states
Section titled “Data and states”Observation IDs and series keys must be unique. Every observation’s series must
match a group key. Coordinates must be finite numbers or null. A point with a
missing coordinate appears in the data table as “No value” and is omitted from
the plot. Bubble sizes must be finite and nonnegative; missing sizes use the
smallest bubble and stay missing in the table. Size is an area measure.
Linear axes accept negative values. Logarithmic axes require positive coordinates
and positive, increasing domain bounds. Invalid data throws an error rather than
silently substituting zero or removing an observation. loading, error, and
empty data render explicit states. Missing-only observations remain in the
hidden data table.
Accessibility
Section titled “Accessibility”title names the figure and summary explains the metrics and units. Focus the
plot and press Left or Right to explore complete observations across all groups.
Escape dismisses point details. A visually hidden native table exposes every
observation, group, coordinate, and size to screen readers with the same
formatters. Figma does not define a visible data disclosure, so the table has no
visible control.
Applications remain responsible for meaningful names, summaries, and units.
API reference
Section titled “API reference”ScatterChartProps inherits figure-compatible HTML attributes except title and
children. className customizes the outer frame.
| Prop | Type | Default | Description |
|---|---|---|---|
title |
string |
Required | Figure name and heading. |
summary |
string |
Required | Meaning and units. |
description |
string |
— | Additional visible explanation. |
data |
readonly ScatterChartPoint[] |
Required | { id, label, series, x, y, size? } observations. |
series |
readonly { key, label, color }[] |
Required | Unique groups. color accepts any ChartColor. |
xAxis, yAxis |
ScatterChartAxis |
Required | { label, scale?, domain?, formatValue? }. Scale defaults to linear; domain follows the data. |
sizeLabel |
string |
Size when size data exists |
Labels the bubble measure and table column. |
formatSize |
(number) => string |
String conversion | Formats sizes in details and the table. |
referenceLines |
readonly ScatterChartReferenceLine[] |
[] |
{ axis: "x" | "y", value, label? } thresholds. |
loading |
boolean |
false |
Shows loading and sets aria-busy. |
error |
string | null |
— | Shows consumer-supplied error text. |
ScatterChartPoint, ScatterChartAxis, ScatterChartReferenceLine, and
ScatterChartProps are exported from the root and named subpath for typed data
and wrappers. Use scale: "log" and a positive [minimum, maximum] domain for
an audience-scale axis. formatValue and formatSize default to string conversion.