Skip to content
WunderUI

Bubble Chart

Pro

Scatter and bubble charts for the relation between two or three values: scatter, bubbles, dot plot, dot matrix, regression, quadrants, beeswarm and a connected scatter.

Playground Bubble Charts

Account health

Account health: 42 points in 3 groups, Monthly active users from 0 to 131, Health score from 0 to 87.
Account health, data table
nameMonthly active usersHealth scoreSizeGroup
Account 11095374Enterprise
Account 219415Mid-market
Account 3745333Startup
Account 41148480Enterprise
Account 5845312Mid-market
Account 6806923Startup
Account 7805597Enterprise
Account 8965431Mid-market
Account 951356Startup
Account 101317011Enterprise
Account 11342824Mid-market
Account 12695318Startup
Account 131005799Enterprise
Account 14543832Mid-market
Account 15254419Startup
Account 1612462111Enterprise
Account 17253430Mid-market
Account 18823921Startup
Account 19994582Enterprise
Account 20324226Mid-market
Account 21444821Startup
Account 22603753Enterprise
Account 2369688Mid-market
Account 24395212Startup
Account 251167323Enterprise
Account 2681639Mid-market
Account 27586823Startup
Account 28945896Enterprise
Account 2954645Mid-market
Account 3053468Startup
Account 311188718Enterprise
Account 3232338Mid-market
Account 33733616Startup
Account 34734156Enterprise
Account 35543315Mid-market
Account 36304829Startup
Account 37604440Enterprise
Account 38304523Mid-market
Account 39354216Startup
Account 40924844Enterprise
Account 41383018Mid-market
Account 42325524Startup

Playground Rows of dots

Feature adoption

Feature adoption: 6 rows, values from 0% to 82%.
Feature adoption, data table
name20262025
Search82%70%
Dashboards74%58%
Exports61%55%
Alerts48%31%
API39%33%
Teams27%14%

Installation

Bubble Chart comes with WunderUI Core and Pro, in the package from your plan. See the plans.

The charts live in their own entry point: import the chart, its card and its hooks from @wunderui/react/charts, not from @wunderui/react.

Then import what you need:

tsx
import {
  BubbleChart,
  BubbleChartProps,
  BubbleChartVariant,
} from "@wunderui/react/charts"

Then use it:

tsx
import { BubbleChart } from "@wunderui/react/charts"

const data = [
  { name: "Account 1", usage: 22, health: 78, seats: 40 },
  { name: "Account 2", usage: 72, health: 92, seats: 120 },
  { name: "Account 3", usage: 124, health: 62, seats: 200 },
]

export function AccountHealth() {
  return <BubbleChart variant="bubble" data={data} index="name" x="usage" y="health" size="seats" label="Account health" />
}

Expected result: You should see three bubbles, the biggest at the lowest health, with usage on the horizontal axis.

When to use

Use Bubble Chart for

  • How two measures relate across many points (usage against health)
  • A third value as the size of the bubble
  • Groups told apart by colour, with a regression line or four quadrants
  • A dot plot or dot matrix per category, a beeswarm, or a path through time

Use something else for

States

Loading, empty and error keep the chart's size, so the card never jumps. Add a retry handler and the error state offers a Try again button.

Account health

Account health: 42 points in 3 groups, Monthly active users from 0 to 131, Health score from 0 to 87.
Account health, data table
nameMonthly active usersHealth scoreSizeGroup
Account 11095374Enterprise
Account 219415Mid-market
Account 3745333Startup
Account 41148480Enterprise
Account 5845312Mid-market
Account 6806923Startup
Account 7805597Enterprise
Account 8965431Mid-market
Account 951356Startup
Account 101317011Enterprise
Account 11342824Mid-market
Account 12695318Startup
Account 131005799Enterprise
Account 14543832Mid-market
Account 15254419Startup
Account 1612462111Enterprise
Account 17253430Mid-market
Account 18823921Startup
Account 19994582Enterprise
Account 20324226Mid-market
Account 21444821Startup
Account 22603753Enterprise
Account 2369688Mid-market
Account 24395212Startup
Account 251167323Enterprise
Account 2681639Mid-market
Account 27586823Startup
Account 28945896Enterprise
Account 2954645Mid-market
Account 3053468Startup
Account 311188718Enterprise
Account 3232338Mid-market
Account 33733616Startup
Account 34734156Enterprise
Account 35543315Mid-market
Account 36304829Startup
Account 37604440Enterprise
Account 38304523Mid-market
Account 39354216Startup
Account 40924844Enterprise
Account 41383018Mid-market
Account 42325524Startup

Hover and trend line

Hover a point and the others step back to the dimmed level; the crosshair, a ring around the point and the value pills on both axes glide to it, and the ring grows or shrinks to the point's size. The regression variant adds the least-squares line, dashed and wiped in after the points, clipped to the plot at both ends so its slope stays true, with R² in the corner.

Account health

Account health: 11 points in 3 groups, Monthly active users from 0 to 172, Health score from 0 to 92.
Account health, data table
nameMonthly active usersHealth scoreGroup
Account 12278Enterprise
Account 27292Enterprise
Account 312462Enterprise
Account 417286Enterprise
Account 53442Mid-market
Account 68868Mid-market
Account 713838Mid-market
Account 816658Mid-market
Account 95222Startup
Account 1010430Startup
Account 1114880Startup

Keyboard interactions

The plot is focusable: arrow keys walk the points in data order and the live region reads each with its axis names, like WunderUI: Revenue $1,200, Margin 24%. Set axis labels so the names are spoken.

TaborShiftTab
Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge.
ArrowRightorArrowLeft
Moves to the next or previous point. The tooltip follows, and a live region announces the one you are on. The first press starts at the first one (Left: the last one).
HomeorEnd
Jumps to the first or last point.
Escape
Clears the active point.
EnterorSpace
On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on.

Behavior and motion

What the chart does on its own and what the page decides.

Fields
The x and y fields name the plotted values, a size field sets the bubble size, and a group field puts a point into a group. Groups are listed in legend order with their colours.
Axes
Value axes start at 0 when every value is positive (you can change that), with titles from the axis labels. Beeswarm and dot plot use one axis and put groups in rows.
Variants
The regression variant draws a fitted line, the quadrant variant four quadrants split at a point you choose, and the connected variant a path through the points in data order.
Legend
Groups switched off in the legend fade, so the points that remain keep their positions.
Loading, empty and error
The chart keeps its size while it loads, is empty or fails, so the card never jumps. Loading shows a skeleton; error adds a Try again button when a retry handler is set.
Legend
A ChartCard shows series as badges. With two or more series each badge switches its series off, the last visible one stays on, and a legend of roles can be made static.
Size
The chart fills its container's width; you set the plot height. Text never scales: labels keep their size at every width.

Motion

The enter sequence and the hover follow the motion tokens of the library.

Pop in
Points pop in from their centre the first time the chart is in view, and again after loading or when new data arrives. You can turn the animation off.
Reduced motion
With reduced motion on, the enter sequence is off and the chart appears at once. Tooltip, crosshair and every state still work.

Anatomy

BubbleChart is the scatter family: scatter, bubbles sized by a third value, dot plot, dot matrix, regression, quadrant, beeswarm and connected scatter. It shows how two measures relate.

Account health

Account health: 11 points in 3 groups, Monthly active users from 0 to 172, Health score from 0 to 92.
Account health, data table
nameMonthly active usersHealth scoreSizeGroup
Account 1227840Enterprise
Account 27292120Enterprise
Account 312462200Enterprise
Account 41728680Enterprise
Account 5344230Mid-market
Account 6886860Mid-market
Account 71383845Mid-market
Account 81665835Mid-market
Account 9522220Startup
Account 101043025Startup
Account 111488018Startup
  • Takes data with x, y and a size per bubble. Groups colour the points and fill the legend, axis labels and formatters name and format the axes, and the quadrant variant sets its own dividers.

  • data-slot="chart-plot"

    The focusable region. Arrow keys walk its marks and the live region reads each one the way the tooltip shows it.

  • data-slot="chart-marks"

    Points that pop in from their centre on the dashed grid of the cartesian charts. The regression line (dashed, wiped in after the points, clipped to the plot with its slope kept), quadrant dividers and the connecting path are drawn behind or over them; groups switched off in the legend go to --chart-hidden. On hover the other points dim, a ring glides to the point and the crosshair and value pills on both axes follow it.

  • Value axes that start at 0 when every value is positive (you can change that), with axis titles. Beeswarm and dot plot use one axis and put the groups in rows.

  • data-slot="chart-tooltip"Optional

    The point label with its x, y and, on bubble charts, its size, using the axis titles as row labels.

  • data-slot="chart-message"Optional

    A loose cloud of muted dots on the scatter variants, muted rows on the dot plot and dot matrix.

  • A table of every point for screen readers.

  • data-slot="chart-active"Optional
  • data-slot="chart-regression"Optional
  • data-slot="chart-crosshair"
  • data-slot="chart-axis-y"
  • data-slot="chart-axis-x"
  • data-slot="chart-axis-pill"

Best practices

  • Do

    Name both axes with axis labels. A scatter without titles cannot be read, and the tooltip uses them for its rows.

  • Do

    Add the regression variant only when a relationship is the claim, and say what the line shows in the card description.

  • Do

    Keep bubble sizes comparable: size encodes area, so a value that varies by a factor of ten needs a visible scale or the label.

  • Don’t

    Don't draw thousands of points in a beeswarm or dot matrix; both are for counts you can read. Aggregate first.

  • Don’t

    Don't colour more than five groups. Keep to the palette and use the legend; the points are small and similar hues merge.

API reference

One table for BubbleChart. It is a plain component, so the table lists every prop; the ChartCard around it takes its own props, and the chart works without one.

Takes data with x, y and a size per bubble. Groups colour the points and fill the legend, axis labels and formatters name and format the axes, and the quadrant variant sets its own dividers.

PropTypeDefaultDescription
data requiredreadonly ChartDatum[]—One object per slice / ring / axis.
index requiredstring—Field holding the label.
xstring"x"Field of the horizontal value. Default "x".
ystring"y"Field of the vertical value (scatter variants). Default "y".
sizestring—: field of the bubble size.
groupstring—Field that puts a point into a group (colour, legend, beeswarm rows).
groupsreadonly BubbleGroup[]—Groups in legend order with their colours (default: in data order, palette colours).
variant"scatter" | "bubble" | "dot-plot" | "dot-matrix" | "scatter-with-regression" | "quadrant-scatter" | "beeswarm" | "connected-scatter""scatter"Figma variant. Default .
xLabelstring—Axis titles (also the tooltip labels).
yLabelstring—
quadrant{ x?: number; y?: number; labels?: readonly [string, string, string, string] }—: where the dividers cross (default: the means) and the corner labels (top left, top right, bottom left, bottom right).
valueFormatterChartValueFormatter—
labelstring—Accessible name, e.g. the card title.
heightnumber434Height of the plot frame in px. Default 280 (Figma small card plot).
state"ready" | "loading" | "empty" | "error"—
activeIndexnumber | null—The active point (hovered or focused) as an index into , to control it yourself. shows none.
animateboolean—
animationKeystring | number—
defaultActiveIndexnumber | null—The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer.
descriptionstring—
emptyDescriptionstring—Text under the title in the empty state.
emptyTitlestring—Title of the message in the empty state.
errorDescriptionstring—Text under the title in the error state.
errorTitlestring—Title of the message in the error state.
hiddenSeriesreadonly string[]—Labels of rows switched off in the legend: drawn faded.
includeZeroboolean—Start the value axes at 0 (default true when all values are positive, as on the bar charts).
onActiveIndexChange(index) => void—Called with the index when the pointer or the arrow keys move to another point, and with when they leave. Use it to show the hovered value in a headline.
onRetry() => void—Shows a Try again button in the error state and calls this when it is pressed.
seriesreadonly ChartSeries[][]: one dot per series and row; : the first series is counted in dots.
tooltipboolean—
unitnumber—: value of one dot. Default: so the largest row has 40 dots.
widthnumber—
xFormatterChartValueFormatter—

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("bubble-chart")
InstallIncluded in Core and Pro

The full library index for assistants is at /llms.txt.