Charts

Scatter Chart

Discover relationships between numeric variables with optional bubble size and categorical color.

Charts / Scatter Chart

Bubble sizingCategory legendReference segmentsKeyboard accessible

Overview

Scatter charts plot numeric x/y pairs as markers. Kamod supports fixed radii, bubble sizing via sizeKey, categorical fills with legend toggles, and reference annotations that render behind or above markers without affecting hit-testing.

import { ScatterChart } from "@kamod-ch/charts/scatter";

Static bundle: Import from @kamod-ch/charts/scatter for charts without the motion runtime. SSR markup is stable before interaction.
Bubble & category modes: Use sizeKey for area-scaled bubbles and categoryKey for per-category colors. Prefer one Y series when coloring by category.

API notes

ScatterChart sizing, categories, tooltips, and reference annotations.

pointRadius vs pointSize: pointRadius sets a fixed marker radius in pixels when sizeKey is not used. pointSize is a legacy alias with identical behavior — prefer pointRadius in new code. Values are radii, not diameters.
sizeKey & sizeScale: sizeKey maps a numeric field to pixel radius through pointRadiusRange (default [4, 18]). sizeScale defaults to "sqrt" so bubble area grows with the data value — a perceptually fair default for counts and volumes. Use "linear" when radius itself should track the value. Override the domain with sizeDomain when needed.
Invalid size values: Missing, negative, non-finite, or null size values are excluded from rendering and hit-testing. The point keeps a safe fallback radius internally but stays invisible when sizeKey is active.
categoryKey & categories: With categoryKey, legend items represent categories (not Y series). Category IDs are stable encodings of string/number values — 1 and "1" differ. Unknown or null categories render with a neutral missing style and can be hidden via the legend. Declare colors in categories or let Kamod assign theme tokens in first-seen order.
ScatterPointContext: Tooltips receive scatterPoint on CartesianTooltipContext with raw xValue, yValue, sizeValue, category fields, and resolved color. Use tooltip.render for fully custom markup; default tooltips append size when present and use category labels in category mode.
referenceSegments: Diagonal segments connect explicit start and end coordinates projected through the same scales as markers. Kamod renders the segment you provide — it does not compute regression or trend statistics. Use precomputed endpoints from your analytics layer.
referenceAreas & referencePoints: Shade acceptable bands with referenceAreas or mark outliers and SLA thresholds with referencePoints. Annotations are aria-hidden, ignore pointer events, and do not affect domains or bubble hit-testing.
SSR & responsive: Pair responsive with initialWidth so the first server render matches your layout width before ResizeObserver measures the container. Tooltips and crosshair stay absent in SSR output until interaction.
Reduced motion: Static @kamod-ch/charts/scatter has no enter/update animation. Import from @kamod-ch/charts/motion when you need transitions and pass animate or wrap with MotionConfig reducedMotion="user" to respect OS settings.

Gallery

Six functional patterns covering basic markers, bubble size, categorical color, custom tooltips, guide segments, and operational air-cargo lanes. Each preview uses Kamod’s real ScatterChart API — no copied option objects.

Basic scatter

One Y series with default marker radius (4px), grid, and nearest tooltip.

single seriesshowGridtooltip

Bubble / sized markers

Map a third numeric field to radius with sizeKey. Defaults to sqrt scaling so bubble area tracks the value; pointRadiusRange caps pixel size.

sizeKeysizeScalepointRadiusRange

Categorical color

Color markers by plan tier. Legend buttons toggle category visibility — use one Y series when categoryKey drives color.

categoryKeycategoriesshowLegend

Bubble + categorical

Combine x, y, size, and category. Custom tooltip.render reads scatterPoint for raw field values.

sizeKeycategoryKeytooltip.render

Guide segment (not regression)

referenceSegments draw a diagonal line between explicit start/end coordinates. Kamod renders your precomputed endpoints — it does not fit regression or compute statistics.

referenceSegments

Rate vs transit time

Operational air-cargo lanes: transit days on X, USD/kg rate on Y, tonnage as bubble size, region as color. Includes a target band and an outlier marker.

sizeKeycategoryKeyreferenceAreasreferencePoints

Scatter chart accessibility

Set title and description on every production chart — they render into SVG title and desc elements.
Scatter uses nearest tooltip mode with bubble-aware hit-testing; keyboard navigation walks valid markers only.
In category mode the legend toggles categories — category label and Y value appear in the default tooltip and live region.
Do not rely on color or bubble area alone: tooltips and keyboard focus expose Y, size, and category text.
Reference segments, areas, and points are decorative (aria-hidden) and never receive pointer hits.
Test light and dark themes with CSS chart tokens; long category labels wrap in the HTML legend.

Props

ScatterChart props
Prop	Type	Default	Description
data	readonly TDatum[]	—	Array of row objects rendered by the chart.
xKey	DataAccessor<TDatum, string \| number \| Date \| null \| undefined>	—	Field or accessor for the x axis.
xScale	"linear" \| "time" \| "band" \| "point"	—	Scale kind for the x axis.
height	number	—	Chart height in pixels.
width	number	—	Fixed width. Prefer responsive + initialWidth for fluid layouts.
initialWidth	number	—	SSR / first-paint width before ResizeObserver measures the container.
responsive	boolean	false	Stretch to the parent container width.
title	string	—	Accessible chart title rendered into SVG title.
description	string	—	Accessible description rendered into SVG desc.
showGrid	boolean	—	Show cartesian grid lines.
showLegend	boolean	—	Show an HTML legend with series toggles. Supported on Line, Scatter, Area, and Bar charts.
tooltip	boolean \| CartesianTooltipOptions<TDatum>	—	Enable pointer and keyboard tooltips. `true` uses chart defaults: axis mode for Line and Area, nearest mode for Scatter and Bar. Options may set mode, placement, offset, render, formatValue, and formatLabel. PieChart does not support this prop.
series	readonly LineSeriesConfig<TDatum>[]	—	One or more line series. LineSeriesConfig extends the cartesian config with strokeWidth, strokeDasharray, showPoints, and pointRadius.
animate	boolean \| ChartAnimateOptions	—	Optional data animation. No-op on static entries unless a MotionConfig from @kamod-ch/charts/motion is present. Defaults to on for charts imported from that subpath. Options: enabled, duration (seconds), easing, preset, reducedMotion.
pointRadius	number \| ((datum, index) => number)	4	Fixed marker radius in pixels when sizeKey is not set. Values are radii, not diameters.
pointSize	number \| ((datum, index) => number)	—	Legacy alias for pointRadius. Prefer pointRadius in new code.
sizeKey	DataAccessor<TDatum, number \| null \| undefined>	—	Numeric field mapped to marker radius via pointRadiusRange. Invalid or negative values hide the marker.
sizeScale	"sqrt" \| "linear"	"sqrt"	Scaling from data value to radius. sqrt (default) maps value to area; linear maps value directly to radius.
sizeDomain	[number, number]	—	Optional override for the inferred size domain. Defaults to data min/max.
pointRadiusRange	[number, number]	[4, 18]	Pixel radius range used when sizeKey is set.
categoryKey	DataAccessor<TDatum, string \| number \| null \| undefined>	—	Field that drives categorical color and category legend. Prefer a single Y series in category mode.
categories	readonly ScatterCategoryConfig[]	—	Optional category metadata (label, color, hidden). IDs are stable encodings of value type.
referenceLines	readonly CartesianReferenceLine<TDatum>[]	—	Optional horizontal or vertical reference lines with label, color, strokeWidth, and strokeDasharray.
referenceSegments	readonly CartesianReferenceSegment<TDatum>[]	—	Diagonal segments between explicit start/end coordinates. Kamod renders provided endpoints — no regression.
referenceAreas	readonly CartesianReferenceArea<TDatum>[]	—	Vertical x1/x2 or horizontal y1/y2 highlight bands clipped to the plot area.
referencePoints	readonly CartesianReferencePoint<TDatum>[]	—	Explicit x/y markers for outliers or SLA points with shape, label, and labelPosition.

ScatterPointContext

Available on CartesianTooltipContext.scatterPoint when a marker is active.

ScatterPointContext fields
Prop	Type	Default	Description
datum	TDatum	—	Active data row.
index	number	—	Row index in data.
xValue / yValue	mixed	—	Raw axis values for the active marker.
sizeValue	number \| null	—	Raw sizeKey value when bubble sizing is enabled.
categoryValue / categoryId / categoryLabel	mixed	—	Resolved category fields when categoryKey is set.
color	string	—	Resolved marker fill used for tooltip swatches in category mode.
radius	number	—	Rendered pixel radius including active-state offset when focused.

referenceSegments entries

CartesianReferenceSegment fields
Prop	Type	Default	Description
start / end	{ x, y }	—	Segment endpoints in data coordinates, projected through chart scales.
labelPosition	"start" \| "middle" \| "end"	"middle"	Label placement along the segment with a perpendicular offset.
strokeWidth / strokeDasharray / class / id	mixed	—	Forwarded to the SVG segment group and line.

referenceAreas & referencePoints

ScatterChart accepts the same CartesianReferenceArea and CartesianReferencePoint shapes as LineChart. Areas render behind grid and markers; points render above series. See the Line chart reference props for field details.

Interaction

Tooltip mode defaults to nearest with bubble-aware hit-testing (edge distance, then center distance).
Keyboard walks valid markers with Arrow, Home, and End; Escape clears the active state.
Legend toggles series in multi-series mode or categories when categoryKey is set.