Skip to documentation content
|

Scatter Chart

A composable scatter chart for relationships, clusters, bubbles, and quadrant analysis.

githubdocapi
Standard Scatter

Overview

Use a scatter chart to inspect relationships between two numeric measures, reveal clusters, and spot outliers. Add bubble sizing when a third measure matters, or divide the plot into labeled quadrants for prioritization and portfolio analysis.

Anatomy

ScatterChart owns the rows, numeric x/y fields, optional grouping, loading state, and selection. Add one Scatter per series, then compose optional Grid, XAxis, YAxis, Legend, Tooltip, and Quadrants parts.

Accessibility

Provide a meaningful ariaLabel and pair the canvas with a table or written summary when point-level data is essential. Tooltips and direct point selection are pointer-operated, so they cannot be the only source of exact values or the only path to an action. Bubble area and quadrant color should supplement labels and values rather than carry meaning alone.

Installation
npm install honestui

Usage

 
import { ScatterChart, type ChartConfig } from "honestui/charts";
<ScatterChart
  data={data}
  config={chartConfig}
  xDataKey="seats"
  yDataKey="adoption"
  groupDataKey="segment"
  pointNameDataKey="account"
>
  <ScatterChart.Grid />
  <ScatterChart.XAxis label="Floor area" />
  <ScatterChart.YAxis label="Energy use" />
  <ScatterChart.Legend />
  <ScatterChart.Tooltip />
  <ScatterChart.Scatter dataKey="enterprise" />
  <ScatterChart.Scatter dataKey="startup" />
</ScatterChart>

When groupDataKey is supplied, each Scatter renders rows whose group value matches its dataKey. Without grouping, a single series renders every row.

Bubble Chart

Bubble Chart

Set variant="bubble" and provide sizeDataKey to encode a third numeric measure by area. minSize and maxSize keep small values visible and large values from overwhelming the plot.

Quadrant Chart

Quadrant Chart

Add Quadrants with numeric split points and optional labels. Honest UI renders quiet analytical regions behind the points while retaining exact x/y positioning.

Loading State

isLoading='true'

The loading state preserves the plot dimensions with neutral placeholder points and the shared chart loading treatment.

API Reference
ScatterChart
PropTypeDefaultDescription
data*TData[]–Rows containing numeric x/y values and optional group, name, and size fields.
config*ChartConfig–Defines labels and theme colors for series and tooltip measures.
xDataKey*keyof TData & string–Numeric field plotted horizontally.
yDataKey*keyof TData & string–Numeric field plotted vertically.
groupDataKeykeyof TData & string–Field used to divide rows between composed series.
pointNameDataKeykeyof TData & string–Field used as the tooltip heading for each point.
animationbooleantrueEnables intro animation unless reduced motion is preferred.
defaultSelectedDataKeystring | nullnullSeries selected on first render.
onSelectionChange(key: string | null) => void–Fires when a clickable point or legend item changes selection.
onPointClick(point: ScatterPoint<TData>) => void–Returns the source row and encoded point values.
isLoadingbooleanfalseShows neutral placeholder points and a loading label.
loadingPointsnumber14Number of loading placeholders.
ariaLabelstring–Accessible name for the canvas chart.
chartOptionsRecord<string, unknown>–Escape hatch merged over generated ECharts options.
Scatter
PropTypeDefaultDescription
dataKey*string–Series identifier and matching ChartConfig key.
variantstandard|bubble"standard"Uses a fixed point size or size encoding.
sizeDataKeystring–Numeric field used by the bubble variant.
symbolScatterSymbol"circle"Point shape.
symbolSizenumber10Fixed size for standard points.
minSizenumber8Smallest bubble diameter.
maxSizenumber44Largest bubble diameter.
fillOpacitynumber0.78Point fill opacity.
isClickablebooleanfalseEnables selection and point click callbacks.
largebooleanfalseEnables ECharts large-data rendering.
largeThresholdnumber2000Point count that activates large rendering.
Quadrants
PropTypeDefaultDescription
xSplit*number–Vertical dividing value.
ySplit*number–Horizontal dividing value.
labelsQuadrantLabels–Labels for the four analytical regions.
showLabelsbooleantrueShows quadrant labels.
XAxis / YAxis
PropTypeDefaultDescription
tickFormatter(value: number, index: number) => string–Formats numeric ticks.
labelstring–Axis title.
hideDotsbooleanfalseHides small tick marks.
minnumber–Explicit lower bound.
maxnumber–Explicit upper bound.
Tooltip
PropTypeDefaultDescription
variantdefault|frosted-glass"default"Tooltip surface treatment.
roundnesssm|md|lg|xl"lg"Tooltip corner radius.
positionfixed|variable"variable"Pins or follows the active point.
xValueFormatter(value: number) => string–Formats the horizontal value.
yValueFormatter(value: number) => string–Formats the vertical value.
sizeValueFormatter(value: number) => string–Formats the bubble-size value.
defaultIndexnumber–Opens a tooltip after mount.
Legend
PropTypeDefaultDescription
variantLegendVariant"circle"Shared Honest UI legend indicator style.
alignleft|center|right"center"Horizontal alignment.
verticalAligntop|middle|bottom"bottom"Placement around the plot.
isClickablebooleanfalseLets legend items isolate a series.