Scatter (S2)

Pre-alpha component

Scatter is a pre-alpha component — it has no finalized Spectrum 2 design yet and is imported from the pre-alpha subpath.

The Scatter component displays scatter plots. Scatter plots use continuous data for both the x and y axes and are most useful for comparing two continuous values across many points.

import { Chart, Axis, Legend } from '@spectrum-charts/react-spectrum-charts-s2';
import { Scatter } from '@spectrum-charts/react-spectrum-charts-s2/pre-alpha';

<Chart data={data}>
  <Axis position="bottom" grid ticks baseline />
  <Axis position="left" grid ticks baseline />
  <Scatter dimension="x" metric="y" color="series" />
  <Legend highlight position="right" title="Series" />
</Chart>

---

Tooltips and popovers

Scatter supports ChartInspect and ChartPopover like other S2 chart mark components. Unlike the base package, S2 does not have a ChartTooltip component — use ChartInspect instead.

<Scatter dimension="x" metric="y" color="series">
  <ChartInspect>
    {(datum) => (
      <div>
        <div>Series: {datum.series}</div>
        <div>Value: {datum.y}</div>
      </div>
    )}
  </ChartInspect>
</Scatter>

---

Path annotations (ScatterPath)

The ScatterPath component draws a continuous path connecting points on the scatter plot. Pass groupBy to control which points are connected — points sharing the same values for all groupBy keys are joined by a path.

<Scatter dimension="x" metric="y" color="series">
  <ScatterPath groupBy={['series']} />
</Scatter>

ScatterPath props

name	type	default	description
color	string	'gray-500'	The color of the path. Accepts a CSS color value or a Spectrum color name.
groupBy	string[]	–	Keys in the data that define which points get connected. Points sharing the same value for every key in groupBy are joined by a path.
pathWidth	string | {value: number}	{value: 'M'}	The width of the path. A string is treated as a key in the data mapped through the path width scale; an object with a value sets a fixed width.
opacity	number	0.5	The fill opacity of the path.

---

Text annotations (ScatterAnnotation)

The ScatterAnnotation component places a text label next to each scatter point. Use textKey to choose which data field to display; if omitted, the label falls back to the Scatter component's own metric field.

<Scatter dimension="x" metric="y" color="series">
  <ScatterAnnotation textKey="label" />
</Scatter>

Labels that don't fit within the chart bounds without overlapping other labels or points are not shown — annotations should be treated as supplemental, "nice to have" information.

ScatterAnnotation props

name	type	default	description
anchor	LabelAnchor | LabelAnchor[]	['right', 'top', 'bottom', 'left']	Where to position the annotation relative to the data point. When an array is provided, each position is tried in order until one fits without overlapping other annotations or points.
textKey	string	(the parent Scatter's metric field)	Key in the data whose value is displayed as the label text.

---

Trendlines (Trendline)

The Trendline component plots a statistical trend calculated from a Scatter's data. Pass a method to control the statistical transform — regression methods ('linear', 'polynomial-2', etc.) draw a fitted curve; aggregate methods ('average', 'median') draw a flat reference line; orientation is only meaningful on scatter plots.

<Scatter color="series" dimension="x" metric="y">
  <Trendline method="linear" lineType="dashed" />
</Scatter>

Trendline supports its own ChartInspect child, independent of the parent Scatter's — use this to show trend-specific values (e.g. the trendline's calculated value via the TRENDLINE_VALUE field) on hover.

Trendline props

name	type	default	description
children	ChartInspect | TrendlineAnnotation	–	Optional child components for trend-specific inspect content and value annotations.
color	string	(parent series color)	The line color of the trendline. Defaults to the color of the series it represents.
dimensionExtent	[number | 'domain' | null, number | 'domain' | null]	(value of dimensionRange)	The dimension range to draw the trendline over. 'domain' extrapolates to the chart's domain edge; null stops at the first/last data point.
dimensionRange	[number | null, number | null]	[null, null]	The dimension range the statistical transform is calculated over.
displayOnHover	boolean	false	When true, the trendline is only visible while hovering the parent Scatter.
excludeDataKeys	string[]	–	Data points where these keys have truthy values are excluded from the trendline calculation.
hidePartialWindows	boolean	false	When true, hides the initial movingAverage-N points calculated from fewer than N data points.
highlightRawPoint	boolean	false	When true and an inspect is present, also highlights the raw scatter point alongside the hovered trendline point.
lineType	LineType	'dashed'	The line type of the trendline.
lineWidth	LineWidth	'M'	The line width of the trendline.
method	'average' | 'median' | 'exponential' | 'linear' | 'logarithmic' | 'polynomial-N' | 'power' | 'quadratic' | 'movingAverage-N'	'linear'	The statistical transform used to calculate the trendline.
opacity	number	1	The opacity of the trendline.
orientation	'horizontal' | 'vertical'	'horizontal'	Orientation of the trendline. Only supported on scatter plots.

Trendline value labels (TrendlineAnnotation)

The TrendlineAnnotation component places a label showing the trendline's calculated value at a point along the trendline.

<Trendline method="median" dimensionExtent={['domain', 'domain']}>
  <TrendlineAnnotation badge prefix="Median:" />
</Trendline>

TrendlineAnnotation props

name	type	default	description
badge	boolean	false	Adds a badge background around the annotation.
dimensionValue	number | 'start' | 'end'	'end'	Where along the dimension scale to label the trendline value.
numberFormat	string	–	A d3-format specifier for the labeled value.
prefix	string	–	Text prepended to the labeled value.

---

Scatter props (S2)

Not all base Scatter props are supported

The S2 Scatter component does not yet support ChartTooltip, onClick, onContextMenu, onMouseOver, or onMouseOut.

name	type	default	description
children	ChartInspect | ChartPopover | ScatterAnnotation | ScatterPath | Trendline	–	Optional child components for inspect panels, popovers, path annotations, and text annotations.
blend	'normal' | Blend	–	CSS blend mode for overlapping points. 'normal' disables blending; other values apply the specified blend mode. Defaults to 'multiply' in light mode and 'screen' in dark mode.
clip	boolean	false	Restricts scatter plot contents to the plot boundaries.
color	string | {value: string}	'series'	Key in the data used to map each point to a color, or a fixed color value object. Also sets the stroke color unless stroke is provided.
colorScaleType	'linear' | 'ordinal'	'linear'	Use 'ordinal' when color maps to string values, or 'linear' when it maps to numeric values.
dimension	string	'x'	Key in the data used for the x-axis value.
lineType	string | {value: LineType | number[]}	{value: 'solid'}	Key in the data for point border line type faceting, or a fixed line type value.
lineWidth	string | {value: number}	{value: 0}	Key in the data for point border width faceting, or a fixed line width value.
metric	string	'value'	Key in the data used for the y-axis value.
name	string	–	Name of the scatter component. Useful when referencing the scatter marks programmatically.
opacity	string | {value: number}	{value: 1}	Key in the data for point opacity faceting, or a fixed opacity value.
size	string | {value: number}	{value: 100}	Key in the data for point size faceting, or a fixed size value.
stroke	string | {value: string}	–	Key in the data used to map each point's border to a color, or a fixed color value. Defaults to color if not provided.