Skip to content
InsightCharts

Search

Search guides and components

Scatter chart

Plots two numeric measures against each other, one dot per row, with optional bubble size, group colour, selective labels and a trend line.

Use when
Showing whether and how two measures move together, spotting clusters and outliers, and placing named entities in a two-dimensional space (with quadrant lines via annotations).
Avoid when
A measure over time (use line chart); one numeric measure by category (use beeswarm chart or strip plot); fewer than about 8 points (use bar chart or a table); more than 4 colour groups (facet with small multiples).

Preview

The United States spent $12,555 per person on health in 2022

Health spending per person (US$, PPP) against life expectancy at birth, OECD countries, 2022. US life expectancy was 77.5 years.

Source: OECD Health Statistics (rounded) · Figures are approximate, for illustration

Composition

  1. Atoms61
  2. Molecules19
  3. Templates20

Used in

No molecule or template lists scatter chart in its composes. It still fits any slot that takes a component.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/scatter-chart

The CLI copies the source into your project and needs the @insightcharts registry in components.json; see installation. With the package, import it by name:

import { ScatterChart } from "insightcharts";

Examples

Bubbles, colour groups, log axis

GDP per person and life expectancy, 104 countries

GDP per person (US$, log scale) against life expectancy. Bubble area is population.

Illustrative data

Quadrants via annotations

Exports is used by 61% of weekly users and rated 2.6 out of 5

Share of weekly users against mean satisfaction, by feature. Dashboards is used by 74% and rated 3.1.

Illustrative data

Stress: 2,400 points with a trend

Floor area and sale price, 2,400 home sales

Floor area in m² against sale price in thousands, with a least-squares trend line

Illustrative data

Props

PropTypeDefaultDescription
xrequiredstringNumeric field on the horizontal axis.
yrequiredstringNumeric field on the vertical axis.
sizestringNumeric field for bubble size; area is proportional to the value.
seriesstringField that colours points by group. Beyond 4 groups the smallest fold into a grey Other.
labelstringField naming each point, for tooltips, direct labels and highlight.
labels"auto" | "all" | "none" | string[]"auto"Which points are labelled. auto: highlighted points, or the outliers when nothing is highlighted. Overlapping labels are hidden.
trendbooleanfalseLeast-squares line of best fit through all points.
logXbooleanfalseLogarithmic x axis.
logYbooleanfalseLogarithmic y axis.
xLabelstringx axis title. Defaults to the field name.
yLabelstringy axis title. Defaults to the field name.
xFormatFormatSpecFormat for x values; format applies to y.
opacitynumberPoint opacity. Default falls as the point count rises.
namesRecord<string, string>Display names for series keys.
Common chart props 29

Every chart built with defineChart accepts these on top of its own props.

PropTypeDescription
dataDataInputRows, CSV text, a URL, { url, path }, an async function, or an Arrow-style table. Omit inside <InsightData>.
transformTransform | Transform[]A pipeline of transforms applied before drawing.
titlestringThe title. One plain statement of what the data shows, with the number and the period ("Monthly churn fell from 4.2% to 2.1% in 2024"), or a plain label ("Monthly churn, 2024"). One clause, no figures of speech.
subtitlestringMeasure, unit, population, period.
sourcestringData source, shown as "Source: ...".
notestringMethod notes or caveats.
heightnumber | stringCSS height of the plot. Default 360.
aspectnumberWidth / height. Overrides height.
highlightstring | string[]The entity (or entities) the title is about. Every other series is drawn in grey.
annotationsAnnotation[]Reference lines, shaded bands and callouts, in data coordinates.
formatFormatSpecHow to print values: "compact", "percent", "currency:USD", "{value} kg", Intl options, or a function.
legendbooleanShow the legend. Default: shown when there are two or more series.
selectboolean | stringMake marks clickable to filter. Inside <InsightData> the selection filters every other chart. Pass a field name, or true to use the chart's category field.
onSelect(values: string[], field: string) => voidCalled with the selected values whenever the selection changes.
optionEChartsOption | ((option: EChartsOption, ctx: BuildContext) => EChartsOption)Deep-merged over the generated ECharts option, or a function that receives and returns it. Use it for ECharts settings no prop covers.
themeThemeInputA theme, or a partial set of tokens merged over the surrounding theme, for this chart only.
modeModeInput"auto" (default) follows the page, "system" follows the OS, or force "light" / "dark".
rendererRendererInput"auto" (default) uses SVG for light charts and canvas for heavy ones.
animatebooleanSet false to disable animation. Reduced-motion preferences are always respected.
lazybooleanMount the chart only when it scrolls near the viewport. Default true.
groupstringLink tooltips with other charts sharing this group id.
exportableboolean | ExportFormat[]Show an export menu: true or a list of formats from png, jpeg, svg, pdf, csv, json.
tablebooleanShow a collapsible "View data" table under the chart.
altstringAccessible description: the chart type and measures, then the main pattern and the notable values.
idstringStable id for this chart's selection in the shared store.
onEventsRecord<string, ChartEventHandler>ECharts event handlers, e.g. { click: (params, chart) => {} }. Prefix a name with zr: to bind to the canvas itself.
onReady(chart: EChartsInstance) => voidCalled with the ECharts instance once it is created.
classNamestringClass name for the outer <figure>.
styleCSSPropertiesInline style for the outer <figure>.