Beeswarm Chart

Preview

Install

1. 1. Add the registry to components.json, once per app. Without it, the shadcn CLI looks up @txbrendan in a public list that txbrendan/ui does not control.

   npx shadcn@latest registry add "@txbrendan=https://txbrendan.dev/r/{name}.json"

2. 2. Add the theme, once per app. It replaces your color tokens with ones checked for contrast.

   npx shadcn@latest add @txbrendan/theme

3. 3. Add the component.

   npx shadcn@latest add @txbrendan/beeswarm-chart

Props

• data

  One object per dot, like { page: "Home", seconds: 1.2 }.

  TData[]

• valueKey

  The number field that places each dot along the axis.

  keyof TData

• config

  Without groupKey, one entry keyed by valueKey. With groupKey, one entry per group value. Colors default to --chart-1 through --chart-5.

  { [key: string]: { label: string; color?: string } }

• labelKey

  The field that names each dot in the tooltip.

  keyof TData

• groupKey

  The field that puts each dot in a group. Dots whose group has no config entry are left out.

  keyof TData

• title

  A visible title. It names the chart. TypeScript requires title, aria-label, or aria-labelledby.

  ReactNode

• aria-label

  Names the chart when it has no visible title.

  string

• size

  Height: 5, 7, or 9 times --control-h-md, so density scales it.

  "sm" | "md" | "lg" · default "md"

• valueFormat

  Formats tooltip values, and axis ticks in short form, like $12.3K.

  Intl.NumberFormatOptions

• locale

  The locale for numbers. Fixed, so server and browser print the same text.

  string · default "en-US"

• legend

  Shows the legend. By default it shows when there are two or more groups.

  boolean

• loading

  Shows a loose swarm of skeleton dots at the same height. When data arrives, they fade out while the dots come in.

  boolean · default false

• error

  Shows this message in place of the chart. true shows a default message.

  ReactNode

• onRetry

  Shows a retry button under the error.

  () => void

• emptyText

  Shown when no dot has a number and a config entry.

  ReactNode · default "No data yet"

• className

  Extra classes. Later classes win, so className='h-96' replaces the height.

  string

Accessibility

• Renders a <figure> named by its title, or by aria-label. TypeScript requires one.
• Recharts' keyboard layer stays on: Tab focuses the chart, the arrow keys step through every dot from the lowest value to the highest, and the tooltip reads each one out.
• The dot the tooltip describes gets a ring, so the arrow keys show where they are.
• Keeps one height while it loads, draws, fails, or has no data, so the page does not move. When the page prints, it asks the browser to keep a chart that fits on one page whole. In the light theme, it asks the browser to print legend dots and loading shapes even with backgrounds off.
• Loading, the error, and the empty text are read out through a status line that stays on the page.
• Group colors come from --chart-1 to --chart-5, which the theme tests hold to 3:1 against the page. The legend and tooltip name each group in text.
• Dots grow in over three times --motion-duration-base, once the chart is on screen. When the data changes, they move, grow, and shrink over the same time. At 0ms they draw at once, and Recharts skips the animation for reduced motion.

Examples

const pages = [
  { page: "Home", seconds: 1.2 },
  { page: "Pricing", seconds: 1.3 },
  { page: "Docs", seconds: 1.25 },
  { page: "Blog", seconds: 2.4 },
];

<BeeswarmChart
  title="Load time by page"
  data={pages}
  valueKey="seconds"
  labelKey="page"
  config={{ seconds: { label: "Load time" } }}
  valueFormat={{ style: "unit", unit: "second", maximumFractionDigits: 2 }}
/>

<BeeswarmChart
  title="Load time by device"
  data={[
    { page: "Home", seconds: 1.2, device: "mobile" },
    { page: "Home", seconds: 0.7, device: "desktop" },
    { page: "Docs", seconds: 1.6, device: "mobile" },
    { page: "Docs", seconds: 0.9, device: "desktop" },
  ]}
  valueKey="seconds"
  labelKey="page"
  groupKey="device"
  config={{ mobile: { label: "Mobile" }, desktop: { label: "Desktop" } }}
/>

const [week, setWeek] = useState("this");

<Tabs value={week} onValueChange={(next) => setWeek(String(next))}>
  <TabsList aria-label="Week">
    <TabsTab value="this">This week</TabsTab>
    <TabsTab value="last">Last week</TabsTab>
  </TabsList>
  <TabsPanel value={week}>
    <BeeswarmChart
      title="Load time by page"
      data={week === "this" ? thisWeek : lastWeek}
      valueKey="seconds"
      labelKey="page"
      config={{ seconds: { label: "Load time" } }}
    />
  </TabsPanel>
</Tabs>

<BeeswarmChart
  aria-label="Load time by page"
  data={data ?? []}
  valueKey="seconds"
  config={{ seconds: { label: "Load time" } }}
  loading={isLoading}
  error={error ? "Load times could not load." : undefined}
  onRetry={() => refetch()}
/>