Scatter Plot
A canvas-rendered scatter plot for correlating two continuous measures (three with the rotatable 3D projection). Compose the gridlines, axes, and one ScatterPlot.Point per series inside ScatterPlot.Root.
When to use
- Show whether two measures are related, such as latency and throughput, payload size and duration, or CPU and memory. Correlation, clusters, and outliers show as shape.
- Correlate three measures in a rotatable 3D cube with
zKeyon the Root. See 3D scatter. - Prefer
LineChartfor the trend of one measure over a continuous x: lines connect ordered samples, and a scatter plot treats each row as an independent observation. - Prefer
BarChartto compare values across discrete categories by bar length from zero.
Point shapes
Every series wears the circle until you set shape. Eight glyphs are available: "circle", "square", "triangle", "diamond", "triangle-down", "plus", "cross", and "star". Mantle never picks one for you, so the glyph is a choice you make beside color.
Give each series its own glyph when clouds overlap. The second channel earns its keep in three places where color alone can fail:
- a reader with a color vision deficiency, who can't hold every hue apart
- print and grayscale exports, which flatten every color to one gray
- a reader who overrides the page's colors, in forced-colors mode for example
The glyph carries the same identity through all three, and it costs nothing: the mark paints some shape either way. color and shape are independent, so two series can share one color and stay apart by glyph.
Every painted mark carries the circle's fill area, so no glyph reads louder than its siblings. The legend keys and hover dots clip those same silhouettes out of a small box, so a spiky glyph like the star reads lighter there than the square.
The encoding is family-wide (the same prop, glyph set, and equal-weight sizing on every chart), and how much of it you see tracks how much of the mark the glyph occupies. Here the glyph is the mark itself. On a line chart it appears on the canvas point markers (when markers is on) and the hover dot. On an area chart a filled band has no per-point mark, so the hover dot and legend key wear it. Bars carry no glyph at all: a bar's identity is its position, its color, and its texture. Legend keys mirror the glyph on every chart form: the glyph itself for scatter points and areas, the glyph riding a short stroke for lines.
US East below sets no shape, so it wears the circle. EU West sets shape="square", and AP South sets shape="star".
Dense scatter
This chart plots 8,000 seeded points in a single series. Rendering degrades by total point count in tiers, never all at once: past 5,000 points the dots drop their 2px surface ring, and past 20,000 they become fast-path rects with no arc calls at all. Hover stays nearest-point at every tier (the hit test walks the data, not the pixels), so a dense cloud is exactly as inspectable as a sparse one. A single series also means no legend: ScatterPlot.Legend renders nothing for one series, because the chart's title already names it.
3D scatter
Set zKey and the scatter renders inside a rotatable cube: drag anywhere in the plot to orbit the camera. The drag captures the pointer, and pitch is clamped so the cube never flips upside down; points depth-sort under a gentle perspective, so nearer points paint over farther ones as the cloud turns. A tap without dragging still inspects and activates the nearest point. The 3D code is a separate chunk that loads when a Root with a zKey mounts, so a page of 2D scatter plots never downloads it, and a 3D chart paints once the chunk arrives. When the load fails, the chart reports the error to the page's error handlers once per attempt. It tries again after 1, 4, and 16 seconds, then on the next press or data update.
Axis parts and reference lines apply to the 2D projection only and are ignored in 3D; the cube frame carries orientation, with each edge labeled by its data key. The hover readout carries the point's z value, and keyboard stepping and the sr-only data table work identically in 3D: arrows walk the projected cloud point by point, announcements append the z value, and the table grows a z column.
The glyphs carry into the projection too, and each one depth-sorts with its point. The three series below wear the circle, the square, and the triangle. The redundant encoding earns its keep in 3D more than anywhere: rotation constantly changes which clouds overlap, and the glyphs keep every series identifiable at any camera angle, with or without color vision.
Dimensions
dimensions controls how many axes the cloud currently occupies: the pattern behind "watch the clusters separate" explainers. At 1 every point collapses onto the x axis line and the four clusters below read as one jumbled strip (only their glyphs still tell them apart); at 2 they spread across the plane; at 3 they fill the cube. Each cluster sets its own shape (circle, square, triangle, diamond), so cluster identity survives even where position collapses. Changing it morphs every point along a smooth glide (the same chase that drives the domains), the y and z frame edges fade in with their dimension, and prefers-reduced-motion snaps the whole move.
Reference lines
ScatterPlot.ReferenceLine paints a dashed horizontal marker at a y value (a target, a budget, an SLO) in the neutral reference color, with an optional label above its right end. Like the axis parts, it applies to the 2D projection only and is ignored in 3D.
Copy as markdown
ScatterPlot.CopyButton copies the chart's current rows to the clipboard as a machine-stable, GitHub-flavored markdown table: one x column plus one column per series in paint order, and the z column in 3D (an ISO 8601 timestamp for every x on a time scale, plain un-separated numbers, an em dash for gaps). The table pastes into Slack, issues, spreadsheets, and LLM chats. The button renders in flow where composed; Root is relatively positioned, so className can dock it over a corner.
Lists of charts
A page of 100 charts pays for the handful a reader can see. A dormant ScatterPlot.Root is a shell: the plot box, the named interaction overlay, and its screen-reader description. It holds no canvas and no engine. The chart activates when it comes within one viewport of the visible area, takes focus, or prints. Activation runs outside React, on-screen charts first, in slices of a few milliseconds with a yield to the browser between them. Each chart paints in the task that activates it. A chart more than three viewports away releases its canvas memory, and it repaints on the way back. Motion plays only while the chart is on screen. A chart that is near the viewport but off screen paints each update settled, with no glide. A print paints every chart settled, with tick labels and gridlines at full opacity. The hover layers and the tooltip surface mount on the first hover. The screen-reader data table waits for focus alone: it mounts once a reader tabs into the chart, so a page of sparklines holds no hidden tables until a reader asks for one. Add content-visibility: auto to your list's cards as a complement: it skips style and layout for offscreen cards, and the chart's own gate already skips paint and canvas memory.
Wrap a list of interactive charts in ScatterPlot.List. The charts inside share one role="status" live region, so a page of 100 charts mounts one region instead of one per chart, plus one for each ScatterPlot.CopyButton. Each chart keeps its own tooltip, description, and data table. Charts of different families can share one List, so one ScatterPlot.List can hold a grid of bar, line, area, and scatter charts. A static chart has no tooltip and no live region, so a list of sparklines needs no List.
Modes
mode sets how much of the chart's contract a Root exposes. Pick by what a reader does with the chart.
Noninteractive is not decorative. A sparkline beside a total still tells a reader when activity happened and how it varied, so it keeps a name and a description; only its values live in the text beside it. One hundred sparklines in a table as one hundred Tab stops is a focus order no reader wants, and a readout that only a pointer can reach fails WCAG 2.2 SC 2.1.1 (Keyboard), so "static" offers neither. A chart that is the only source of its values stays "interactive".
Static charts
Set mode="static" for a chart a reader glances at while the exact values sit beside it. The plot is a named role="img": it takes the same aria-label or aria-labelledby an interactive chart does, and its aria-describedby points at the description, so a screen reader hears the chart kind, the point count, the x range, and the series labels without a Tab stop. There is no interaction overlay: no hover band, no tooltip, no keyboard point cursor, no data table, and no live region, and a composed ScatterPlot.Tooltip has no effect. Pointer events pass through to the row or card behind it. The series keep their colors. animate defaults to false, because a list of sparklines that each play a reveal as the reader scrolls is motion with no information in it; pass animate to play the reveal. The interaction props (activeIndex, onActiveIndexChange, onDatumActivate) are forbidden at the type level. The Sparklines in a List recipe is the worked example.
Decorative charts
Set mode="decorative" to render the chart as a placeholder backdrop instead of real data: synthetic points behind an empty state, an atmospheric hero graphic. A decorative chart keeps its visual rendering and animation but drops every layer that only makes sense for real data: it is hidden from assistive technology, removed from the tab order, and inert to pointer and keyboard, with no hover band, tooltip, sr-only data table, or live region. Because the values aren't information, mode="decorative" is mutually exclusive with the accessible-name props (aria-label / aria-labelledby) and the interaction props (activeIndex, onActiveIndexChange, onDatumActivate); the type won't compile with both.
A decorative chart also drops the series colors. Every series paints --color-chart-decorative, one neutral fill that outranks a series' color. A backdrop carries no series identity, and a hue on values that are not information invites a reader to decode it.
That fill is what keeps an overlaid message readable. Empty.Description sits on text-muted, which measures 4.88:1 on a bare light card (0.38 over the 4.5:1 floor for 14px text), so any tint under that copy spends the headroom. --color-chart-decorative is the darkest neutral step that still clears the floor in both themes: 4.56:1 in light and 4.93:1 in dark. The message needs no scrim behind it, no dimming, and no blur. Redeclare the token on the Root to retune the fill (className="[--color-chart-decorative:var(--color-neutral-100)]") and re-measure the copy against the value you pick.
Reach for mode="decorative" over hand-rolled inert + CSS: it removes the interaction overlay at the source, so consumers never target chart internals to neutralize it. Keep the real empty-state message as a sibling of the chart (not inside it) so screen readers still announce it; the decorative chart itself is silent.
mode="decorative" says the values are not information; it is not a disabled flag (a chart is not a form control). For real data a reader only glances at, use mode="static".
Composition
Compose the parts of a ScatterPlot together to build your own:
The interaction layer ships with Root, and there is no part to add for it: the tooltip, keyboard stepping, polite announcements, and a screen-reader description. The screen-reader data table mounts once the chart takes focus. If you remove a part, keyboard access to the data stays.
Hover hits the nearest point within 24px of the pointer, so a 4px dot is never a pinpoint target. The tooltip names only the series of the hit point. Compose ScatterPlot.Legend on every multi-series chart. Series identity must never rely on color alone.
Wrap a list of Roots in ScatterPlot.List so they share one live region:
Axes
Every mark is one independent observation, placed by two continuous values.
Scatter x values must be continuous: numbers or Dates. A scatter plot has no categorical axis.
Color and accessibility
Scatter is the strictest chart form for color. A point can land next to a point from any other series, so every pair of colors on the plot must stay apart, not only the neighbors in the legend. Mantle doesn't guarantee that any set of names stays apart for color-blind readers, so make the choice on purpose:
- Pick colors that differ in lightness as well as hue.
- Set a different
shapeon each series when clouds overlap. The glyph keeps every series apart without color vision, in print, and in forced-colors mode. Point shapes lists the glyphs. - Give the "Other" series
color="neutral".
Each point needs 3:1 contrast against the card. A 4px dot is a small mark, so a low-contrast name such as yellow in light mode is hard to find on the plot. Pick another name there, or add a shape and visible value labels.
The Bar Chart page covers the rest: the WCAG contrast rules, the measured contrast of each name, and when a chart is exempt.
Keep a chart to eight series
Show the top seven series, plus one "Other" series that sums the tail and has color="neutral". Scatter is an all-pairs chart form: any point can land next to any point from any other series. So every pair of series colors must stay apart, not only the neighbors in a legend. To show more series, facet into small multiples. The Bar Chart page has a worked fold.
Accessibility
Every interactive chart must have an accessible name: either a direct aria-label or an aria-labelledby reference to a visible title (preferred when the chart sits under a heading: no drift-prone duplicated text). This is enforced at the type level: omitting both is a compile error, not a runtime warning. The name lands on the focusable interaction overlay, the chart's single named element (the canvas itself is hidden from assistive technology so the chart is never announced twice). A static chart names its plot role="img" instead and has no Tab stop. A decorative chart carries no real data, so it takes no accessible name and is hidden from assistive technology entirely.
The chart is a single tab stop with a full keyboard point cursor, identical in 2D and 3D:
Escape, Enter, and Space act only while a point is active. An idle Escape therefore reaches the surface around the chart, such as a panel that closes on Escape. A held Enter or Space activates once, and a chord with Alt, Ctrl, or Meta passes through to the browser. With a pointer, only the primary button activates a point. In forced-colors mode, the focused chart shows a focus outline, and the hover dot stays visible.
The tooltip names only the relevant series, never a column of em dashes: under the pointer it reads the hit point's series, and under keyboard stepping it reads the row's populated series. Keyboard stepping announces the active point through a debounced polite aria-live region, so rapid arrowing never floods the screen-reader queue. In 3D, the announcement carries the point's z value. Announcements follow keyboard steps only: the chart doesn't announce a data update while the keyboard cursor rests on a point. When the labelFormat or valueFormat of a composed ScatterPlot.Tooltip returns a string or a number, the announcement uses it. The data table keeps the default number format.
The overlay's aria-describedby points at a screen-reader description, data-slot="scatter-plot-description", so a screen reader hears what the chart holds when it takes focus: the chart kind, the number of data points, the x range from the first point to the last, the series labels, and the keyboard instructions. For example: "Scatter plot with 120 data points from 1 to 2,400. Series: Checkout, Search. Use the left and right arrow keys to move between data points, …". An empty chart reads "Scatter plot with no data." in place of the count and range. Server HTML carries the plain count alone. The range waits for hydration, because Intl output differs by locale, and the series labels register in layout effects, so both render on the client.
The 3D orbit is pointer-only and needs a drag. The cube has no keyboard control (WCAG 2.2 SC 2.1.1, Keyboard) and no single-pointer control that works without a drag (SC 2.5.7, Dragging Movements). Rotation changes the view, not the data, so a keyboard user still reaches the points through the point cursor and the data table.
Every chart also renders a screen-reader-only data table once it takes focus: one column for the x value and one per series (plus a z column in 3D), bounded to the first 150 rows with a caption stating the summarization. A ScatterPlot.Root mounts dormant and engages once focus lands inside it (the overlay is the Tab stop, and a focusable part composed inside the Root, such as ScatterPlot.CopyButton, counts too), and it never goes dormant again. Visibility paints the chart but never mounts the table. The Root stamps data-state="dormant", then data-state="engaged", and the table mounts with the flip, so a screen reader's table list names only the charts the reader has focused. The description above names what every chart holds, focused or not. Tooltips enhance, they never gate. The keyboard point cursor steps one point at a time at any density, so it reaches every point. The table holds the first 150 rows, and ScatterPlot.CopyButton copies every row.
The table doubles as the chart's machine-readable surface. On a "time" scale, every row header carries its x (a Date, an epoch number, or a date string) as an ISO 8601 timestamp in <time dateTime>. Value cells carry the raw number in data-value, so agents and scrapers read precise data from the DOM without reverse-engineering locale formatting. A row whose x has no text form, such as null or a date that doesn't parse, shows an em dash. Assistive tech still hears the human-formatted text, and the table itself is addressable at data-slot="scatter-plot-data-table". To reach it, an agent focuses the chart (a scroll into view is not enough), then waits for data-state="engaged" on the Root. ScatterPlot.CopyButton hands over the same rows as markdown with neither step.
The Bar Chart page lists the accessibility limits that every chart family shares, such as the pause control that a live chart needs from your page.
API Reference
ScatterPlot.Point, ScatterPlot.Grid, ScatterPlot.XAxis, ScatterPlot.YAxis, and ScatterPlot.ReferenceLine are renderless: they register configuration with the Root, which paints everything on canvas. They accept no className and no DOM props. ScatterPlot.Tooltip, ScatterPlot.Legend, and ScatterPlot.CopyButton are the parts that touch real DOM. The first two accept div props, and CopyButton accepts button props. Grid, XAxis, YAxis, and ReferenceLine configure the 2D projection only: composing them is always safe, but they are ignored while the chart renders in 3D. ScatterPlot.List renders a div around a list of Roots.
ScatterPlot.Root
The root of a scatter plot: owns the data, the scales, the canvas renderer, and the entire interaction contract. Renders a <div> wrapper (defaulting to a 16:9 aspect ratio, overridable via className) that holds the focusable interaction overlay, the sr-only description, and, outside a List, the aria-live region. The canvas, the crosshair, hover-band, and marker layers, and the sr-only data table arrive later: the data attributes below say when. Hovering hits the nearest point within 24px (never a pinpoint target); the tooltip reads that point's series, x, and y (and z in 3D). Points never stack, so there is no stacked prop.
All props from div, plus:
Data attributes
ScatterPlot.Point
One point series. It renders nothing itself: it registers the series with the chart, which paints its points on canvas: 4px dots with a 2px surface ring, degrading gracefully past thousands of points (see Dense scatter). Compose one Point per series, eight or fewer (see Color and accessibility).
ScatterPlot.Grid
Hairline gridlines behind the points. Renderless (painted on canvas); 2D only (the 3D cube frame carries orientation). Omit the part to omit the grid.
ScatterPlot.XAxis
Value labels along the bottom of the plot. Renderless (painted on canvas); 2D only. Labels that would collide are skipped, never rotated.
ScatterPlot.YAxis
Value tick labels along the left of the plot. Renderless (painted on canvas); 2D only. Ticks land on clean thousands-separated numbers.
ScatterPlot.ReferenceLine
A dashed horizontal marker at a y value, such as a target, a budget, or an SLO threshold. Renderless (painted on canvas); 2D only (ignored in the 3D projection).
ScatterPlot.Tooltip
Customizes the hover/keyboard tooltip readout. The tooltip itself is part of ScatterPlot.Root's interaction contract and renders even when this part is absent. Compose it to format the label or values, append a footer, or replace the content entirely.
A children readout renders inside a <div data-slot="scatter-plot-tooltip-label">. When it goes away, React removes that div instead of your own text nodes: a browser translation engine reparents text nodes, and a removal aimed at one throws. The div is display: contents, so it adds no box and your content stays a direct layout child of the parent. To style it as a box, set a display of your own on it first. Browser translation covers the mechanism and the rules your own components need.
The footer and children render props receive a HoverSnapshot: the active index, xValue, the original datum, points, viaKeyboard, and zValue in 3D. Scatter points are filtered to the relevant series: the hit point's series under the pointer, the row's populated series under the keyboard.
All props from div (forwarded to the tooltip element the Root renders) except children, plus:
Data attributes
ScatterPlot.Legend
The legend: series names keyed by swatches carrying each series' color and glyph, rendered as real DOM in flow below the plot. Always compose it on multi-series charts: identity must never rely on color-matching alone. It renders nothing for a single series (the chart's title already names it). The legend is at most 64px tall (max-h-16) and scrolls past that, so many series never take the plot's height in a fixed-height Root. Set a max-h-* class in className to change the bound.
A children render prop renders inside a <div data-slot="scatter-plot-legend-label">. When it goes away, React removes that div instead of your own text nodes: a browser translation engine reparents text nodes, and a removal aimed at one throws. The div is display: contents, so it adds no box and your content stays a direct layout child of the parent. To style it as a box, set a display of your own on it first. Browser translation covers the mechanism and the rules your own components need.
All props from div except children, plus:
Data attributes
ScatterPlot.CopyButton
A button that copies the chart's current data to the clipboard as a GitHub-flavored markdown table: one x column, one column per series in paint order, plus the z column in 3D. Values are machine-stable (an ISO 8601 timestamp for every x on a time scale, plain un-separated numbers, an em dash for gaps), so the paste target receives parseable data, not locale formatting. Renders an icon button in flow where composed; Root is relatively positioned, so className can dock it over a corner (e.g. absolute right-0 top-0).
All props from button, plus:
While a copy is fresh, an always-mounted role="status" element beside the button announces "Copied" to a screen reader.
ScatterPlot.List
Groups a list of charts, such as one chart per card, so they share one role="status" live region. A page of 100 charts mounts one region instead of one per chart, plus one for each ScatterPlot.CopyButton. Each chart keeps its own tooltip, description, and data table. Charts of different families can share one List. See Lists of charts.
Renders a div (scatter-plot-list) that holds the charts in a display: contents wrapper (scatter-plot-list-items), so a grid or flex layout on the List reaches the cards, and the live region as its last child. ScatterPlot.List takes no asChild: a list element such as ul cannot hold the live region as a child.
All props from div.
Chart color tokens
Every mantle color name has one chart token, --color-chart-<name>, and a series with color="<name>" paints it. These are the same names Badge takes.
Pick a functional name when a series means good or bad: danger for an error rate, success for a pass rate. Give an "Other" series neutral.
The color prop also takes any CSS color string. A static color (a raw hex) can't follow the two themes, so prefer a var(...) reference to a token you declare per theme.
Series color
Change a series color in one of two ways:
- Set
coloronScatterPlot.Pointto a color name or any CSS color string. - Redeclare a token on
ScatterPlot.Root, such asclassName="[--color-chart-blue:var(--color-brand)]". Every series that wearsblueon that chart picks up the new value, and so do its legend key and hover dot.
The chart resolves every token from Root's computed style in one read, inside that Root's own cascade, so a declaration scoped to one Root wins for that chart alone. Sibling charts on the page keep the theme value. A bare currentColor resolves from Root's computed color. A value the canvas cannot parse by itself, such as light-dark() or a currentColor nested inside color-mix(), resolves through a hidden element inside Root instead. Declare the same custom property higher up (on a dashboard wrapper, or at :root) to retheme a whole subtree.
Mantle measures only its own tokens. Check a value you set against the card in both themes, and against every other color on the plot, because scatter marks meet at every pair. The chart below restyles blue to a brand color, and EU West passes a CSS color string.