Unit barsFree
How many units per category, countable?
npx shadcn@latest add https://beautifulcharts.dev/r/unit-bars.jsonEngine: ·
Every option in the CustomizerUsage
A complete client module. Install the item first, then paste it into your app.
"use client";
import { UnitBarsBlock, type UnitRow } from "@/components/beautiful-charts/blocks/instrument/unit-bars";
// Your rows, in this shape. A missing value is null and stays a gap; the stats and copy recompute.
const data: UnitRow[] = [{ size: "XS", units: 6 }, { size: "S", units: 14 }, { size: "M", units: 19 }, { size: "L", units: 11 }, { size: "XL", units: 4 }];
export function Dashboard() {
return <UnitBarsBlock data={data} />;
}
Props
data
UnitRow[]
Your rows (
UnitRow = { size: string; units: number | null }). Missing values arenulland stay gaps; with no rows every stat shows a dash. Leave it out to see the sample.stats
ChartStat[] | false
The stat row: computed from the data by default; pass your own, or false to hide it. A row of figures under the title, for dashboard cards and blocks.
footer
ReactNode | false
The line at the bottom: pass your own, or false to hide it. A line or action at the bottom of the card, e.g. a source note or a link.
| Prop | Type | Description |
|---|---|---|
| data | UnitRow[] | Your rows (UnitRow = { size: string; units: number | null }). Missing values are null and stay gaps; with no rows every stat shows a dash. Leave it out to see the sample. |
| stats | ChartStat[] | false | The stat row: computed from the data by default; pass your own, or false to hide it. A row of figures under the title, for dashboard cards and blocks. |
| footer | ReactNode | false | The line at the bottom: pass your own, or false to hide it. A line or action at the bottom of the card, e.g. a source note or a link. |
Every bar chart prop works too, so you can restyle it without touching the source.
Sourcecomponents/beautiful-charts/blocks/instrument/unit-bars.tsx
Show the source (21 lines)
"use client";
import { BarChart, type BarChartProps } from "../../themes/instrument/recharts/bar-chart";
import { formatWith, num, pickStats, sumOf, valuesOf, type BlockOptions } from "../block";
export type UnitRow = { size: string; units: number | null };
/** Sample: units shipped this week by size, small enough to count block by block. */
export const unitSample: UnitRow[] = [{ size: "XS", units: 6 }, { size: "S", units: 14 }, { size: "M", units: 19 }, { size: "L", units: 11 }, { size: "XL", units: 4 }];
/** "How many units per category, countable?" Each block is one unit, so small numbers read exactly. */
export function UnitBarsBlock({ data = unitSample, stats, footer, ...chart }: BlockOptions<UnitRow> & Partial<BarChartProps<UnitRow>>) {
const top = data.filter((row) => row.units !== null).sort((a, b) => b.units! - a.units!)[0];
const fmt = formatWith(chart.valueFormatter, num);
const missing = data.length - valuesOf(data, "units").length;
return (
<BarChart data={data} readout={false} xKey="size" eyebrow="Warehouse" title="Units shipped by size" config={{ units: { label: "Units", fill: "blocks" } }} highlight="max" showValues
stats={pickStats(stats, [{ label: missing ? "Units, sizes logged" : "Units", value: fmt(sumOf(data, "units")), note: missing ? `${missing} missing` : undefined }, { label: "Best seller", value: top?.size ?? "—", note: top ? `${fmt(top.units)} units` : undefined }])}
footer={footer === false ? undefined : footer} {...chart} />
);
}
Details
Props every chart shares (34): data, config, header, states, legend, tooltip, formatting, motion and selection
data*
TDatum[]
Your rows, as they are. Missing values (null, undefined, NaN) stay missing and are never drawn as zero.
locale
string
BCP 47 locale. Defaults to "en-US" so server and client render the same text.
timeZone
string
IANA time zone for dates. Defaults to "UTC" so server and client agree.
config
ChartConfig
Per-series label, colour, icon, format and style, keyed by series key. shadcn ChartConfig works as it is.
eyebrow
ReactNode
Small label above the title.
title
ReactNode
Card title. A string also names the chart for screen readers.
description
ReactNode
A line under the title.
takeaway
ReactNode | ((summary: string) => ReactNode) | false
The sentence under the title. Computed from the data by default; pass text, a function of the computed sentence, or false to hide it.
ariaDescription
string
Accessible summary for screen readers. Computed from the data by default.
motion
MotionPreference
"full" (default), "subtle" or "off". Reduced-motion settings always win.
motionOptions
MotionOptions
When the entrance plays.
sound
boolean
Sound cues on hover, scrub and select. Plays only if the visitor has also turned sound on for the page.
density
Density
"comfortable" (default) or "compact" for dashboards.
legend
LegendOptions | false
Legend position, alignment, shape and click action, or false to hide it.
tooltip
TooltipOptions<TDatum> | false
Tooltip position, indicator, cursor and custom content, or false to turn it off.
valueFormatter
(value: number) => string
Values formatted for display. Series formatters in config win.
loading
boolean
Show the loading state. Over existing data, the old marks stay dimmed instead of vanishing.
error
string | null
An error message. Shows the error state in place of the plot.
emptyState
ReactNode
Shown instead of the plot when there is no data.
loadingState
ReactNode
Shown while
loadingis true and there is no data yet.errorState
ReactNode
Shown when
erroris set.selected
number | null
Controlled and uncontrolled interaction state. Point selection (
selected) pins one row by its index indata. Series selection (selectedSeries) picks one series and dims the others. They are separate: picking a row doesn't pick a series.defaultSelected
number | null
Initial selected row when uncontrolled.
selectedSeries
string | null
Controlled series selection: this series stays lit and the others dim.
defaultSelectedSeries
string | null
Initial series selection when uncontrolled.
hidden
string[]
Controlled hidden series keys.
defaultHidden
string[]
Series hidden at first when uncontrolled.
activeIndex
number | null
Controlled hover or focus index, for syncing several charts on one cursor.
palette
"theme" | "shadcn"
Series colours: "theme" (default) uses the theme's designed palette; "shadcn" uses your --chart-1..5. --bc-series-N always wins. You can also opt a whole section in with the class bc-use-shadcn-colors.
table
boolean
Show the "Show data table" disclosure. On by default.
stats
ChartStat[]
A row of figures under the title, for dashboard cards and blocks.
footer
ReactNode
A line or action at the bottom of the card, e.g. a source note or a link.
className
string
Classes on the card, for spacing and layout.
height
number
Height of the plot area in px. The frame sizes around it.
| Prop | Type | Description |
|---|---|---|
| data* | TDatum[] | Your rows, as they are. Missing values (null, undefined, NaN) stay missing and are never drawn as zero. |
| locale | string | BCP 47 locale. Defaults to "en-US" so server and client render the same text. |
| timeZone | string | IANA time zone for dates. Defaults to "UTC" so server and client agree. |
| config | ChartConfig | Per-series label, colour, icon, format and style, keyed by series key. shadcn ChartConfig works as it is. |
| eyebrow | ReactNode | Small label above the title. |
| title | ReactNode | Card title. A string also names the chart for screen readers. |
| description | ReactNode | A line under the title. |
| takeaway | ReactNode | ((summary: string) => ReactNode) | false | The sentence under the title. Computed from the data by default; pass text, a function of the computed sentence, or false to hide it. |
| ariaDescription | string | Accessible summary for screen readers. Computed from the data by default. |
| motion | MotionPreference | "full" (default), "subtle" or "off". Reduced-motion settings always win. |
| motionOptions | MotionOptions | When the entrance plays. |
| sound | boolean | Sound cues on hover, scrub and select. Plays only if the visitor has also turned sound on for the page. |
| density | Density | "comfortable" (default) or "compact" for dashboards. |
| legend | LegendOptions | false | Legend position, alignment, shape and click action, or false to hide it. |
| tooltip | TooltipOptions<TDatum> | false | Tooltip position, indicator, cursor and custom content, or false to turn it off. |
| valueFormatter | (value: number) => string | Values formatted for display. Series formatters in config win. |
| loading | boolean | Show the loading state. Over existing data, the old marks stay dimmed instead of vanishing. |
| error | string | null | An error message. Shows the error state in place of the plot. |
| emptyState | ReactNode | Shown instead of the plot when there is no data. |
| loadingState | ReactNode | Shown while loading is true and there is no data yet. |
| errorState | ReactNode | Shown when error is set. |
| selected | number | null | Controlled and uncontrolled interaction state. Point selection (selected) pins one row by its index in data. Series selection (selectedSeries) picks one series and dims the others. They are separate: picking a row doesn't pick a series. |
| defaultSelected | number | null | Initial selected row when uncontrolled. |
| selectedSeries | string | null | Controlled series selection: this series stays lit and the others dim. |
| defaultSelectedSeries | string | null | Initial series selection when uncontrolled. |
| defaultHidden | string[] | Series hidden at first when uncontrolled. |
| activeIndex | number | null | Controlled hover or focus index, for syncing several charts on one cursor. |
| palette | "theme" | "shadcn" | Series colours: "theme" (default) uses the theme's designed palette; "shadcn" uses your --chart-1..5. --bc-series-N always wins. You can also opt a whole section in with the class bc-use-shadcn-colors. |
| table | boolean | Show the "Show data table" disclosure. On by default. |
| stats | ChartStat[] | A row of figures under the title, for dashboard cards and blocks. |
| footer | ReactNode | A line or action at the bottom of the card, e.g. a source note or a link. |
| className | string | Classes on the card, for spacing and layout. |
| height | number | Height of the plot area in px. The frame sizes around it. |
Events (5)
onSelectedChange
(selection: Selection<TDatum> | null) => void
Called when a row is selected or cleared, by pointer, keyboard or the data table.
onSelectedSeriesChange
(key: string | null) => void
Called when the selected series changes (legend "select" action, or a click on a series).
onHiddenChange
(hidden: string[]) => void
Called when the legend hides or shows a series.
onActiveChange
(index: number | null) => void
Called as the hovered or focused row changes, or null when it leaves.
onReady
(chart: EChartsType) => void
ECharts build only. Called once with the ECharts instance, e.g. to add event listeners.
| Prop | Type | Description |
|---|---|---|
| onSelectedChange | (selection: Selection<TDatum> | null) => void | Called when a row is selected or cleared, by pointer, keyboard or the data table. |
| onSelectedSeriesChange | (key: string | null) => void | Called when the selected series changes (legend "select" action, or a click on a series). |
| onHiddenChange | (hidden: string[]) => void | Called when the legend hides or shows a series. |
| onActiveChange | (index: number | null) => void | Called as the hovered or focused row changes, or null when it leaves. |
| onReady | (chart: EChartsType) => void | ECharts build only. Called once with the ECharts instance, e.g. to add event listeners. |
Recharts build only (1)
children
ReactNode
Recharts children render inside the chart: reference areas, custom labels, anything Recharts accepts.
| Prop | Type | Description |
|---|---|---|
| children | ReactNode | Recharts children render inside the chart: reference areas, custom labels, anything Recharts accepts. |
Apache ECharts build only (2)
renderer
EChartsRenderer
"canvas" (default, best for large data) or "svg".
option
OptionOverride
Deep-merged over the generated ECharts option (plain objects merge; arrays and class instances replace), or a function that receives the generated option and returns the final one. See the chart docs.
| Prop | Type | Description |
|---|---|---|
| renderer | EChartsRenderer | "canvas" (default, best for large data) or "svg". |
| option | OptionOverride | Deep-merged over the generated ECharts option (plain objects merge; arrays and class instances replace), or a function that receives the generated option and returns the final one. See the chart docs. |
- Pointer
- Hover shows a crosshair and a tooltip with every series at that point; click pins it. Clicking a legend item hides or shows its series.
- Keyboard
- Tab lands once on the plot. Left and Right move between points (the first press goes to the latest), Up and Down change series, Home and End jump to the ends, Enter or Space pins, Escape clears.
- Screen readers
- Every move is announced as a sentence, not coordinates. "Show data table" opens the numbers as a real table, and missing values stay empty, never zero.
- Motion
- Bars grow from the baseline, staggered in data order, then the labels fade in. The headline number rolls in. With reduced motion everything appears settled at once, and nothing depends on the motion to be read.