shadcn.io is an independent project built on shadcn/ui
Installation
The command adds the example above to components/charts/ and, the first time, the chart kit to components/ui/charts/. Both are source files in your project from then on: read them, change them, delete what you don't use.
Usage
One row per observation. With categoryKey, each category gets its own swarm.
<script lang="ts">
import {
Beeswarm,
BeeswarmChart,
BeeswarmTooltip,
BeeswarmXAxis,
BeeswarmYAxis,
Grid,
} from "@/components/ui/charts";
// One row per production deploy.
const data = [
{ minutes: 11.2, team: "Payments" },
{ minutes: 9.4, team: "Payments" },
{ minutes: 17.7, team: "Payments" },
{ minutes: 13.1, team: "Payments" },
{ minutes: 6.8, team: "Search" },
{ minutes: 8.1, team: "Search" },
{ minutes: 7.6, team: "Search" },
{ minutes: 10.9, team: "Search" },
];
const formatMinutes = (value: number) => `${value} min`;
</script>
<BeeswarmChart ariaLabel="Deploy duration by team" categoryKey="team" {data}>
<Grid horizontal={false} vertical />
<Beeswarm dataKey="minutes" label="Deploy" />
<BeeswarmXAxis formatValue={formatMinutes} />
<BeeswarmYAxis />
<BeeswarmTooltip />
</BeeswarmChart>Anatomy
Each Beeswarm adds a dot per row. The value sets a dot's place along the value axis, and the packing spreads it across its category's band.
<BeeswarmChart categoryKey="team" {data}>
<Grid horizontal={false} vertical />
<Beeswarm dataKey="minutes" fill="var(--chart-1)" label="Deploy" />
<BeeswarmXAxis />
<BeeswarmYAxis />
<BeeswarmTooltip />
</BeeswarmChart>BeeswarmChart: Packs the dots into one band per category, or a single band withoutcategoryKey.Grid: Guide lines along the value axis, soverticalon the default layout.Beeswarm: One series: a dot for each row'sdataKeyvalue.BeeswarmXAxis: Values on the default layout, categories on a vertical one.BeeswarmYAxis: Categories on the default layout, values on a vertical one.BeeswarmTooltip: The hovered dot's value and category.
One swarm, two series
Leave out categoryKey and every row goes into one swarm across the plot. Add a Beeswarm for each column you want to compare, and the series pack together, each in its own color.
That makes a shift between two samples easy to see without summarizing either of them.
Vertical swarms
The default layout runs values along the bottom with a row per category. orientation="vertical" stands each swarm up as a column instead.
A swarm wider than its band is squeezed back into it, so dots can end up touching. Lower radius when that happens.
How many dots
Packing checks each dot against the ones already placed, so the work grows quickly with the count. A few hundred dots is comfortable. For thousands, a histogram or a violin plot shows the same distribution for far less.
Customization
The kit is in your project, in components/ui/charts/: your framework's components over a shared core/. Change a default there and every chart picks it up.
class goes on the chart's container, so size and spacing are utility classes.
The tooltip's content gets the hovered dot's value, its category, its series' label and color, and the source row. Reach into row to show the other columns of that record.
On a Beeswarm, radius sets the dot radius (4 px) and fadedOpacity how far the other dots dim while one is hovered (0.3).
<BeeswarmTooltip>
{#snippet content({ point })}
<TooltipContent
rows={[
{ color: point.color, label: "Duration", value: `${point.value} min` },
{ color: point.color, label: "Service", value: String(point.row.service) },
]}
title={point.category}
/>
{/snippet}
</BeeswarmTooltip>Where a part renders content of its own, you pass it in. In Svelte:
BeeswarmTooltip:{#snippet content({ point, index })}
Loading state
With status="loading" the chart packs a skeleton swarm for each category (three with no data) and ignores the pointer. loadingLabel adds a line of text. On "ready" the real dots pop in.
Render <BeeswarmChartLoading /> when there are no rows to pass yet. It takes orientation, so it can match a vertical chart.
Animation
Dots pop in from the lowest value to the highest. Each pop lasts 420 ms, and the start times are spread over the rest of animationDuration (1100 ms). animate={false} on a Beeswarm places its dots at once.
When the data changes, dots glide to their new spots over 500 ms. Reduced motion turns off the pop and the glide.
Theming
Every color in the kit is one of your theme's tokens or a mix of them, except --chart-positive, a fixed green. A preset or the .dark class restyles the chart, and overriding a token in your CSS changes it everywhere.
Each Beeswarm takes fill, or the next of --chart-1 to --chart-5. The hovered dot is redrawn on top of the dimmed swarm with a ring in --chart-background.
| Token | Default | Paints |
|---|---|---|
--chart-1 | your theme's | the first series |
--chart-2 | your theme's | the second series |
--chart-3 | your theme's | the third series |
--chart-background | --card | dot halos, the gaps between stacked marks |
--chart-grid | --border | grid lines |
--chart-label | --muted-foreground | tick labels |
--chart-foreground-muted | --muted-foreground mixed toward --background | skeletons and faded marks |
--chart-tooltip-background | --popover | the tooltip panel |
:root {
--chart-background: var(--background);
--chart-grid: var(--muted);
}Accessibility
The chart is an image named by ariaLabel ("Beeswarm chart" by default). Every dot is a keyboard stop, so with more than a few dozen, put the takeaway in ariaDescription rather than expecting anyone to step through them.
- Tab
- Moves focus to the chart and rings the first dot.
- Arrow Right
- Moves to the next dot, left to right. ArrowDown does the same.
- Arrow Left
- Moves to the previous dot. ArrowUp does the same.
- Home
- Jumps to the first dot.
- End
- Jumps to the last dot.
API reference
Svelte takes the same props as React, with class for className. Render props are snippets, listed below by their names. Keep data in $state.raw so the chart sees each new array.
BeeswarmChart
categoryKey?string
Key of the column naming each row's category: one swarm per category, in first-seen order. Without it, one swarm across the plot.
orientation?"vertical" | "horizontal"
"horizontal": values along the bottom, each category's swarm a row. "vertical": values up the side, each swarm a column.
- Type
"vertical" | "horizontal"- Default
"horizontal"
domain?readonly [number, number]
The value axis range [min, max]. Defaults to the observations' extent, rounded to nice values.
datareadonly DistributionRow[]
The observations, one object per row. Each series reads its dataKey column; rows without a finite number there are skipped.
aspectRatio?string
Width to height ratio of the chart, for example "2 / 1" or "16 / 9".
- Default
"2 / 1"
margin?Partial<ChartMargin>
Space around the plot in pixels, per side. Each side defaults to fit the chart's axes.
- Type
Partial<ChartMargin>
animationDuration?number
Duration of the entrance in milliseconds.
- Default
1100
ariaLabel?string
Accessible name of the chart. Defaults to its kind, for example "Histogram" or "Box plot".
ariaDescription?string
Accessible description of the chart.
status?ChartStatus
"loading" draws a shimmering skeleton shaped like the chart in place of its marks and ignores the pointer; switching to "ready" plays the entrance. Switching back to "loading" fades the marks out first.
- Default
"ready"
loadingLabel?string
Text shown centered over the plot, with a shimmer, while status is "loading". Nothing is shown when it is unset or empty.
class?string
Class names added to the chart's container.
style?CSSProperties
Inline styles for the chart's container.
children?ReactNode
The chart's parts: its series, Grid, axes and tooltip.
Beeswarm
radius?number
Radius of each dot in pixels.
- Default
4
dataKeystring
Key of the numeric column this series reads from each row.
label?string
The series' name in the tooltip and legend. Defaults to dataKey.
fill?string
Fill colour. Defaults to the series' palette colour, var(--chart-1) for the first.
stroke?string
Outline colour. Defaults to the fill.
fadedOpacity?number
Opacity of the other items while one is hovered (and of the other series while a legend row is).
- Default
0.3
animate?boolean
Play the entrance.
- Default
true
Grid
horizontal?boolean
Show horizontal grid lines.
- Default
true
vertical?boolean
Show vertical grid lines.
- Default
false
numTicksRows?number
Number of horizontal grid lines. Ignored when rowTickValues is set.
- Default
5
numTicksColumns?number
Number of vertical grid lines.
- Default
10
rowTickValues?number[]
Explicit y values for the horizontal grid lines. Overrides numTicksRows.
stroke?string
Color of the grid lines.
- Default
"var(--chart-grid)"
loadingStroke?string
Grid color while the chart is loading. Falls back to stroke.
strokeOpacity?number
Opacity of the grid lines.
- Default
1
strokeWidth?number
Width of the grid lines in px.
- Default
1
strokeDasharray?string
Dash pattern of the grid lines.
- Default
"4,4"
highlightRowValues?number[]
Y values of horizontal lines drawn with the highlight styling, for example a zero baseline.
highlightRowStroke?string
Color of the highlighted rows.
- Default
"var(--chart-foreground-muted)"
highlightRowStrokeOpacity?number
Opacity of the highlighted rows.
- Default
1
highlightRowStrokeWidth?number
Width of the highlighted rows in px.
- Default
1
highlightRowStrokeDasharray?string
Dash pattern of the highlighted rows.
- Default
"0"
fadeHorizontal?boolean
Fade the horizontal lines toward transparent at the left and right edges.
- Default
true
fadeVertical?boolean
Fade the vertical lines toward transparent at the top and bottom edges.
- Default
false
hideHorizontalEdgeLines?boolean
Drop the first and last horizontal line (kept when two or fewer remain).
- Default
false
hideVerticalEdgeLines?boolean
Drop the first and last vertical line (kept when two or fewer remain).
- Default
false
shimmer?boolean
While the chart is loading, sweep a bright band across the grid.
- Default
false
shimmerStroke?string
Color of the shimmer band.
- Default
"color-mix(in oklch, var(--bkm-foreground) 68%, transparent)"
shimmerSpeed?number
Speed multiplier of the shimmer sweep. 2 is twice as fast.
- Default
1
BeeswarmXAxis
numTicks?number
Target number of tick labels on a value axis.
- Default
5
formatLargeNumbers?boolean
Abbreviate values of 1000 and above as thousands, for example 2k or 1.5k. Ignored when formatValue is set.
- Default
true
formatValue?(value: number) => string
Formats a value tick into its label, for example (value) => \${value} ms\``.
- Type
(value: number) => string
BeeswarmYAxis
numTicks?number
Target number of tick labels on a value axis.
- Default
5
formatLargeNumbers?boolean
Abbreviate values of 1000 and above as thousands, for example 2k or 1.5k. Ignored when formatValue is set.
- Default
true
formatValue?(value: number) => string
Formats a value tick into its label, for example (value) => \${value} ms\``.
- Type
(value: number) => string
BeeswarmTooltip
content?Snippet<[{ point, index }]>
Replaces the default panel body (a title over one row per value) with your own content for the hovered item.
- Type
Snippet<[{ point, index }]>
formatValue?(value: number) => string
Formats the values the default body shows. Defaults to the chart's value axis formatValue, else en-US numbers.
- Type
(value: number) => string
BeeswarmChartLoading
orientation?"vertical" | "horizontal"
"vertical": the skeleton's categories along the bottom. "horizontal": down the side. Defaults to the chart's own default.
- Type
"vertical" | "horizontal"
aspectRatio?string
Width to height ratio of the placeholder, for example "2 / 1".
- Default
"2 / 1"
margin?Partial<ChartMargin>
Space around the plot in pixels, per side.
- Type
Partial<ChartMargin>
label?string
Text shown centered over the skeleton, with a shimmer. Nothing is shown when it is unset or empty.
class?string
Class names added to the placeholder's container.
- Default
""
Examples
4 examples on Svelte, each live with its code and its own install command.
