# Bubble Chart

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.

- Category: Charts
- Page: https://wunderui.com/components/bubble-chart
- Tier: Core and Pro

## Install

Bubble Chart ships with WunderUI Core and Pro in the @wunderui/react package.

## Import

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

## Minimal usage

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

- [Line Chart](https://wunderui.com/components/line-chart) for a measure over ordered time
- [Heatmap](https://wunderui.com/components/heatmap) for a value for every pair of two categories
- [Distribution Chart](https://wunderui.com/components/distribution-chart) for how one measure spreads
- [Bar Chart](https://wunderui.com/components/bar-chart) for values per category

## Keyboard

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.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the plot and away from it. The plot is one tab stop; so is every legend badge. |
| `ArrowRight` or `ArrowLeft` | 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). |
| `Home` or `End` | Jumps to the first or last point. |
| `Escape` | Clears the active point. |
| `Enter` or `Space` | On a legend badge of a ChartCard: switches its series off or on. The last visible series stays on. |

## Behavior

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`: 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.
- `Plot`: The focusable region. Arrow keys walk its marks and the live region reads each one the way the tooltip shows it.
- `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.
- `Axes`: 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.
- `Tooltip`: The point label with its x, y and, on bubble charts, its size, using the axis titles as row labels.
- `Loading, empty and error`: A loose cloud of muted dots on the scatter variants, muted rows on the dot plot and dot matrix.
- `Data table and live region`: A table of every point for screen readers.
- `Chart Active`
- `Chart Regression`
- `Chart Crosshair`
- `Chart Axis Y`
- `Chart Axis X`
- `Chart Axis Pill`

## Best practices

### When to use

- Use BubbleChart to find clusters, outliers or a relationship between two measures. For a trend over time use LineChart, and for ranking use BarChart.

### Do

- Name both axes with axis labels. A scatter without titles cannot be read, and the tooltip uses them for its rows.
- Add the regression variant only when a relationship is the claim, and say what the line shows in the card description.
- 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 colour more than five groups. Keep to the palette and use the legend; the points are small and similar hues merge.

## API reference

### BubbleChart

| Prop | Type | Default | Description |
|---|---|---|---|
| data* | readonly ChartDatum[] |  | One object per slice / ring / axis. |
| index* | string |  | Field holding the label. |
| activeIndex | number \| null |  | The active point (hovered or focused) as an index into `data`, to control it yourself. `null` shows none. |
| animate | boolean |  |  |
| animationKey | string \| number |  |  |
| className | string |  | Extra classes for the root element of the chart. |
| defaultActiveIndex | number \| null |  | The point that is active at first, for an uncontrolled chart. It shows the tooltip without a pointer. |
| description | string |  |  |
| emptyDescription | string |  | Text under the title in the empty state. |
| emptyTitle | string |  | Title of the message in the empty state. |
| errorDescription | string |  | Text under the title in the error state. |
| errorTitle | string |  | Title of the message in the error state. |
| group | string |  | Field that puts a point into a group (colour, legend, beeswarm rows). |
| groups | readonly BubbleGroup[] |  | Groups in legend order with their colours (default: in data order, palette colours). |
| height | number | 434 | Height of the plot frame in px. Default 280 (Figma small card plot). |
| hiddenSeries | readonly string[] |  | Labels of rows switched off in the legend: drawn faded. |
| includeZero | boolean |  | Start the value axes at 0 (default true when all values are positive, as on the bar charts). |
| label | string |  | Accessible name, e.g. the card title. |
| onActiveIndexChange | (index: number \| null) => void |  | Called with the index when the pointer or the arrow keys move to another point, and with `null` 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. |
| quadrant | { x?: number; y?: number; labels?: readonly [string, string, string, string] } |  | `quadrant-scatter`: where the dividers cross (default: the means) and the corner labels (top left, top right, bottom left, bottom right). |
| series | readonly ChartSeries[] | [] | `dot-plot`: one dot per series and row; `dot-matrix`: the first series is counted in dots. |
| size | string |  | `bubble`: field of the bubble size. |
| state | "ready" \| "loading" \| "empty" \| "error" |  |  |
| tooltip | boolean |  |  |
| unit | number |  | `dot-matrix`: value of one dot. Default: so the largest row has 40 dots. |
| valueFormatter | ChartValueFormatter |  |  |
| variant | "scatter" \| "bubble" \| "dot-plot" \| "dot-matrix" \| "scatter-with-regression" \| "quadrant-scatter" \| "beeswarm" \| "connected-scatter" | "scatter" | Figma variant. Default `scatter`. |
| width | number |  |  |
| x | string | "x" | Field of the horizontal value. Default "x". |
| xFormatter | ChartValueFormatter |  |  |
| xLabel | string |  | Axis titles (also the tooltip labels). |
| y | string | "y" | Field of the vertical value (scatter variants). Default "y". |
| yLabel | string |  |  |

## Examples

### States

### Hover and trend line

## In context

### Customer Health Quadrant

Accounts by usage and health, split into four quadrants.

## For AI agents

`get_component("bubble-chart")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
