Skip to content
InsightCharts

Search

Search guides and components

Circle pack

Shows parts as tightly packed circles sized by value, optionally clustered into groups, with the value and name printed inside each circle.

Use when
A poster view of 5 to about 60 parts of very different sizes where the reader should see the largest ones and their rough proportions at once: budgets by programme, emissions by source, users by product. One level of grouping is supported.
Avoid when
Values that need precise comparison (use bar chart, where bars share a baseline); parts that must visibly add up to a whole (use treemap or waffle chart); more than about 80 parts (use treemap); negative values (use diverging bar chart).

Preview

Composition

  1. Atoms61
  2. Molecules19
  3. Templates20

Used in

1 infographic uses circle pack.

Infographics

1

Ranking poster

A poster of one subject by the numbers, in four rows: two figures in large type or as filled silhouettes, two treemaps side by side, a full-width ranking of centred pills with one row highlighted, and packed circles with icons beside a column of sized circles and a closing figure.

Installation

$ pnpm dlx shadcn@latest add @insightcharts/circle-pack

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 { CirclePack } from "insightcharts";

Examples

Flat, with highlight, icons and a size key

Shaded by value inside one ring

Stress: 27 circles in 5 groups, long names, values from 2 to 1,280

Props

PropTypeDefaultDescription
namerequiredstringName field: one circle per row.
valuerequiredstringValue field: circle area. Non-positive values are dropped.
groupstringParent field. Circles sharing a group sit together and share a colour.
ring"none" | "group" | "all"Thin dotted enclosing ring: one per group with its name and total, or one around the whole pack. Default "group" when group is set, else "none".
colorBy"group" | "value" | "single"Colour by group, shade by value along the sequential ramp, or use the accent for every circle. Default "group" when group is set, else "single".
iconstring | Record<string, string>Icon drawn above the number in large circles: one for all, or a map from circle or group name to icon. Built-in name or path://.
sizeLegendboolean | number[]falseSize key of nested reference circles. true picks round values; an array sets them.
labelsbooleantruePrint names and values inside circles, and beside the ones too small to hold them.
namesRecord<string, string>Display names for group 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>.