/// Charts

BubbleChart

A monochrome-plus-signal bubble chart — a scatter plot with a third (size) dimension mapped through a recharts ZAxis.

import { BubbleChart } from "@protocore/pds";

View as Markdown

Import path

BubbleChart ships from the `@protocore/pds/charts` subpath. recharts (>=3) is an optional peer.

import { BubbleChart } from "@protocore/pds/charts";
import { ChartContainer } from "@protocore/pds";

Basics

Give it data, a numeric xKey, a zKey for the size dimension, and one or more series (each key is the y value). Bubble area encodes zKey between zRange; the fill is a translucent ramp hue with a hairline outline so overlaps stay readable.

Risk / impact / effort

When to use it

Use BubbleChart when a third measure — volume, weight, count — matters alongside an x/y correlation. Without that third dimension, reach for ScatterChart. Keep bubbles translucent so dense clusters remain legible, and rank series by luminance on the ramp.

Usage

Map a meaningful magnitude to `zKey` — area reads as quantity.
Wrap it in a ChartContainer so it inherits the `--pds-chart-*` ramp.
Tune `zRange` so the smallest bubble is still visible and the largest doesn't dominate.
Give each series a human `label` for the tooltip and legend.

Don't

Don't encode area by radius yourself — pass `zKey` and let recharts scale area.
Don't use opaque fills that hide overlapping bubbles.
Don't import it from `@protocore/pds`; it lives on the `/charts` subpath.
Don't add more than a couple of series — bubbles crowd fast.

Accessibility

recharts renders the plot as SVG; provide surrounding context for assistive tech.
Area encodes magnitude independently of colour, so quantity stays readable in grayscale.

`BubbleChart` props

Prop	Type	Default	Description
`data` *	`ReadonlyArray<Record<string, string \| number \| null \| undefined>>`	—	Row-oriented data; each datum keyed by `xKey`, `zKey`, and every series `key` (its y value).
`series` *	`ChartSeries[]`	—	Series to plot, in draw + legend order. `ChartSeries` = `{ key: string; label?: string; color?: string }` — each `key` is the datum's y value.
`xKey` *	`string`	—	Datum key for the numeric x-axis value.
`zKey` *	`string`	—	Datum key for the bubble-size (z) dimension.
`zRange`	`[number, number]`	`[60, 600]`	Bubble area range `[min, max]` in px².
`height`	`number`	`240`	Chart height in px.
`...rest`	`Omit<RechartsScatterChartProps, 'data' \| 'children' \| 'width' \| 'height' \| 'ref'>`	—	Remaining props spread onto the underlying recharts `<ScatterChart>`.