Charts

ScatterPlot

A scatter plot for visualizing correlations between two numeric dimensions with multi-series support.

import { ScatterPlot } from "metricui";

Use ScatterPlot to explore correlations — MRR vs seats, revenue vs headcount, spend vs conversion rate. Supports multiple series, node sizing, reference lines, cross-filtering, and drill-down. For categorical comparison use BarChart; for time-series trends use LineChart.

Basic Example

MRR vs Seats

<ScatterPlot
  data={accountData}
  index="mrr"
  categories={["seats"]}
  title="MRR vs Seats"
  xFormat="currency"
  yFormat="number"
  height={300}
/>

Node Sizing

Use the nodeSize prop to control dot size in pixels.

Large Nodes

<ScatterPlot
  data={accountData}
  index="mrr"
  categories={["seats"]}
  title="Large Nodes"
  nodeSize={14}
  height={300}
/>

Multiple Series

Pass Nivo-native series data with id and data arrays to render multiple colored series with a legend.

Accounts by Segment

<ScatterPlot
  data={[
    { id: "Enterprise", data: [{ x: 120, y: 22000 }, ...] },
    { id: "Mid-Market", data: [{ x: 45, y: 8200 }, ...] },
    { id: "SMB", data: [{ x: 15, y: 3200 }, ...] },
  ]}
  title="Accounts by Segment"
  xFormat="number"
  yFormat="currency"
  height={350}
/>

Reference Lines

Add horizontal or vertical reference lines for targets or thresholds.

MRR vs Seats — with Target

<ScatterPlot
  data={accountData}
  index="mrr"
  categories={["seats"]}
  title="MRR vs Seats — with Target"
  xFormat="currency"
  height={300}
  referenceLines={[
    { axis: "x", value: 15000, label: "Target MRR", color: "#EF4444", style: "dashed" },
  ]}
/>

Props

Prop	Type	Default	Description
`data`	`ScatterPlotDatumInput[] \| DataRow[]`	—	Nivo-native scatter series or flat DataRow[] with index/categories.
`index`	`string`	—	X-axis field name for flat-row mode.
`categories`	`Category[]`	—	Y-axis field(s) — each becomes a series (flat-row mode).
`xFormat`	`FormatOption`	—	Format for x-axis values.
`yFormat`	`FormatOption`	—	Format for y-axis values.
`title`	`string`	—	Chart card title.
`subtitle`	`string`	—	Chart card subtitle.
`description`	`string \| React.ReactNode`	—	Description popover content.
`footnote`	`string`	—	Footnote below the chart.
`action`	`React.ReactNode`	—	Action slot in the top-right corner.
`height`	`number`	`300`	Chart height in px.
`colors`	`string[]`	—	Series colors. Default: theme series palette.
`nodeSize`	`number`	`8`	Node (dot) size in px.
`enableGridX`	`boolean`	`true`	Show X-axis grid lines.
`enableGridY`	`boolean`	`true`	Show Y-axis grid lines.
`referenceLines`	`ReferenceLine[]`	—	Horizontal or vertical reference lines for targets/benchmarks.
`animate`	`boolean`	`true`	Enable/disable chart animation.
`legend`	`boolean \| LegendConfig`	—	Legend configuration. Default: shown for multi-series data.
`crossFilter`	`boolean \| { field?: string }`	—	Enable cross-filtering. true uses serieId as the field, or pass { field } to override.
`drillDown`	`true \| ((event: ScatterNodeClickEvent) => React.ReactNode)`	—	Drill-down. true = auto table, function = custom content.
`drillDownMode`	`"slide-over" \| "modal"`	`"slide-over"`	Drill-down presentation mode.
`tooltipHint`	`boolean \| string`	—	Show action hint in tooltip.
`xAxisLabel`	`string`	—	X-axis label.
`yAxisLabel`	`string`	—	Y-axis label.
`onNodeClick`	`(event: ScatterNodeClickEvent) => void`	—	Click handler for nodes.
`variant`	`CardVariant`	—	Card variant.
`dense`	`boolean`	—	Compact layout.
`className`	`string`	—	Additional CSS class names.
`classNames`	`{ root?: string; header?: string; chart?: string; body?: string; legend?: string }`	—	Sub-element class name overrides.
`id`	`string`	—	HTML id attribute.
`data-testid`	`string`	—	Test id.
`loading`	`boolean`	—	Loading state.
`empty`	`EmptyState`	—	Empty state configuration.
`error`	`ErrorState`	—	Error state configuration.
`stale`	`StaleState`	—	Stale data indicator.

Data Shape

// Nivo-native format
type ScatterPlotDatumInput = {
  id: string;
  data: { x: number; y: number }[];
};

// Flat-row format (converted via index + categories)
type DataRow = { [key: string]: string | number };

Notes

Uses forwardRef.
Accepts two data modes: Nivo-native series ({ id, data: [{ x, y }] }) or flat DataRow[] with index + categories.
Reference lines support both x-axis (vertical) and y-axis (horizontal) with label, color, and style options.
Linked hover highlights matching series nodes when hovering in sibling charts.
X/Y axis ticks and labels auto-hide at narrow container widths (<300px).
The aiContext prop (inherited from BaseComponentProps) adds business context for AI Insights analysis. See the AI Insights guide for details.