Skip to content

Scatter Chart

⋯

Content performance

Retention and engagement percentages. Bubble area measures views. These values are synthetic.

  • Content
Content performance data
CategoryRetentionEngagementViews
Tutorial (Content)42%6%24000
Review (Content)25%3%11000

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.

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.

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.

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.