Skip to content
InsightCharts

Search

Search guides and components

Beeswarm chart

Shows a distribution as one dot per row along a value axis, with dots stacked sideways where they would collide.

Use when
Showing a distribution while keeping every individual visible: 30 to about 2,000 named things (countries, players, schools), optionally in a few rows by group, with one or two highlighted.
Avoid when
More than about 2,000 rows or when only the summary matters (use histogram or box plot); many groups with few rows each (use strip plot); two numeric measures (use scatter chart).

Preview

Nigeria had 107.2 under-five deaths per 1,000 live births in 2022

Deaths before age five per 1,000 live births, 84 countries, 2022

Source: UN IGME (rounded) · Figures are approximate, for illustration

Composition

  1. Atoms61
  2. Molecules19
  3. Templates20

Used in

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

Installation

$ pnpm dlx shadcn@latest add @insightcharts/beeswarm-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 { BeeswarmChart } from "insightcharts";

Examples

Rows by group, with medians

Height of 380 professional basketball players by position

Height in centimetres. The tick marks the median of each position.

Illustrative data

Colour by series, long format

Base salary by team and level

Thousands of dollars, 210 employees

Illustrative data

Highlight a whole row

Base salary by team

Thousands of dollars, 210 employees. Support is highlighted.

Illustrative data

Stress: 2,000 dots

Duration of 2,000 bike-share trips

Minutes per trip

Illustrative data

Props

PropTypeDefaultDescription
valuerequiredstringNumeric field that positions each dot along the axis.
groupstringField that splits the dots into rows, one swarm per group.
seriesstringField that colours dots by category. Beyond 6 categories the rest turn grey.
labelstringField naming each dot, for tooltips, highlight and labels on highlighted dots.
radiusnumberDot radius in px. Default 5 down to 3 by row count; shrinks if a swarm would overflow its row.
medianbooleanfalseMark each row's median with a vertical tick.
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>.