React BarChart: examples and API

Preview

Live preview

Changes apply to this preview only.

Use arrow keys to explore values, Home and End to jump, Escape to dismiss.

Fictional BarChart dataset data
Label	Value
Design	24
Engineering	38
Product	19

Loading the interactive example?

Width adapts to the available space

"use client";

import { BarChart } from "@pimolu/react";

export function BarChartExample() {
  const data = [
    { label: "Design", value: 24 },
    { label: "Engineering", value: 38 },
    {
      label: "Product",
      value: 19
    }
  ];
  return (
    <BarChart
      aria-label="Fictional BarChart dataset"
      data={data}
      yAxisLabel="Completed tasks"
    />
  );
}

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Grouped comparisons

Compare delivered work by team and month.

Open preview

Stacked totals

Combine series into a total for each month.

Open preview

Horizontal categories

Give longer category labels more room.

Open preview

Named-part customization

Style this chart directly through typed geometry and surface hooks.

Open preview

Usage

Use data for a single series or series and labels for grouped comparisons. Set stacked or horizontal for a different comparison. Values represent non-negative magnitudes.

Use valueFormatter for readable units. These charts do not implement zoom, pan or time-axis aggregation. Demo data is fictional.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluChartDatum

Type source

PimoluChartDatum public API
Name	Type	Default	Description
`label`Required	`string`	—	Category label shown on the axis, in the legend and in the data table.
`value`Required	`number`	—	Numeric value of the category.
`color`	`string \| undefined`	—	Explicit colour. Falls back to the chart palette and theme tokens.

labelRequired: string
No default extracted.
Category label shown on the axis, in the legend and in the data table.
valueRequired: number
No default extracted.
Numeric value of the category.
color: string | undefined
No default extracted.
Explicit colour. Falls back to the chart palette and theme tokens.

PimoluChartSeries

Type source

PimoluChartSeries public API
Name	Type	Default	Description
`name`Required	`string`	—	Series name used by the legend and the data table.
`values`Required	`number[]`	—	One value per category. Missing trailing values are allowed.
`color`	`string \| undefined`	—	Explicit colour. Falls back to the chart palette and theme tokens.

nameRequired: string
No default extracted.
Series name used by the legend and the data table.
valuesRequired: number[]
No default extracted.
One value per category. Missing trailing values are allowed.
color: string | undefined
No default extracted.
Explicit colour. Falls back to the chart palette and theme tokens.

PimoluBarChartProps

Type source

PimoluBarChartProps public API
Name	Type	Default	Description
`classNames`	`PimoluClassNames<"chart"> \| undefined`	—	Additive classes for stable named parts, including composed descendants. Parts: area, axis, axisLabel, axisTitle, bar, canvas, centerLabel, centerValue, cursor, donutTrack, empty, grid, legend, legendItem, legendLabel, legendSwatch, legendValue, line, point, root, segment, srOnly, svg, tooltip, tooltipRow, valueLabel. Parts render only when the corresponding component or state is present.
`responsive`	`boolean \| undefined`	`true`	Fits the drawing coordinates to the container to keep text legible. Defaults to true.
`data`	`PimoluChartDatum[] \| undefined`	`[]`	Simple category/value data. Use with `label`, `value` and an optional per-category `color`.
`series`	`PimoluChartSeries[] \| undefined`	`[]`	Multi-series data. When several series are supplied the bars are grouped by default; set `stacked` to stack them.
`labels`	`string[] \| undefined`	`"1", "2", ..`	Category labels for `series`. Defaults to "1", "2", ...
`max`	`number \| undefined`	—	Upper bound of the value axis. Derived from the data when omitted.
`stacked`	`boolean \| undefined`	`false`	Stacks series instead of grouping them side by side.
`horizontal`	`boolean \| undefined`	`false`	Draws bars from left to right and category labels on the Y axis.
`showValues`	`boolean \| undefined`	`false`	Prints the numeric value next to each bar (or above a stack).
`showGrid`	`boolean \| undefined`	`true`	Shows the value grid. Defaults to true.
`xAxisLabel`	`string \| undefined`	—	Optional title under the category axis.
`yAxisLabel`	`string \| undefined`	—	Optional title beside the value axis.
`width`	`number \| undefined`	—	Initial viewBox width, default 640 (240 for DonutChart). Bar/Line/Area measure their container by default; set responsive=false to retain this viewBox width and the original fluid aspect ratio.
`height`	`number \| undefined`	`320 (or 240 for the donut)`	viewBox height. Responsive Cartesian charts retain this drawing height. Defaults to 320 (or 240 for the donut).
`showLegend`	`boolean \| undefined`	—	Shows the legend below the chart.
`showTooltip`	`boolean \| undefined`	`true`	Enables pointer, touch and arrow-key exploration. Defaults to true.
`interactionLabel`	`string \| undefined`	—	Localized instructions for keyboard exploration.
`valueFormatter`	`((value: number) => string) \| undefined`	—	Formats values in the axis, value labels, legend and data table.
`emptyLabel`	`string \| undefined`	—	Text announced when there is nothing to draw.
`onChange`	`ChangeEventHandler<HTMLDivElement, Element> \| undefined`	—	Standard React/HTML attribute.
`defaultValue`	`string \| number \| readonly string[] \| undefined`	—	Standard React/HTML attribute.
`className`	`string \| undefined`	—	Standard React/HTML attribute.
`style`	`CSSProperties \| undefined`	—	Standard React/HTML attribute.
`aria-label`	`string \| undefined`	—	Defines a string value that labels the current element.
`onClick`	`MouseEventHandler<HTMLDivElement> \| undefined`	—	Standard React/HTML attribute.

classNames: PimoluClassNames<"chart"> | undefined
No default extracted.
Additive classes for stable named parts, including composed descendants. Parts: area, axis, axisLabel, axisTitle, bar, canvas, centerLabel, centerValue, cursor, donutTrack, empty, grid, legend, legendItem, legendLabel, legendSwatch, legendValue, line, point, root, segment, srOnly, svg, tooltip, tooltipRow, valueLabel. Parts render only when the corresponding component or state is present.
responsive: boolean | undefined
Default: true
Fits the drawing coordinates to the container to keep text legible. Defaults to true.
data: PimoluChartDatum[] | undefined
Default: []
Simple category/value data. Use with `label`, `value` and an optional per-category `color`.
series: PimoluChartSeries[] | undefined
Default: []
Multi-series data. When several series are supplied the bars are grouped by default; set `stacked` to stack them.
labels: string[] | undefined
Default: "1", "2", ..
Category labels for `series`. Defaults to "1", "2", ...
max: number | undefined
No default extracted.
Upper bound of the value axis. Derived from the data when omitted.
stacked: boolean | undefined
Default: false
Stacks series instead of grouping them side by side.
horizontal: boolean | undefined
Default: false
Draws bars from left to right and category labels on the Y axis.
showValues: boolean | undefined
Default: false
Prints the numeric value next to each bar (or above a stack).
showGrid: boolean | undefined
Default: true
Shows the value grid. Defaults to true.
xAxisLabel: string | undefined
No default extracted.
Optional title under the category axis.
yAxisLabel: string | undefined
No default extracted.
Optional title beside the value axis.
width: number | undefined
No default extracted.
Initial viewBox width, default 640 (240 for DonutChart). Bar/Line/Area measure their container by default; set responsive=false to retain this viewBox width and the original fluid aspect ratio.
height: number | undefined
Default: 320 (or 240 for the donut)
viewBox height. Responsive Cartesian charts retain this drawing height. Defaults to 320 (or 240 for the donut).
showLegend: boolean | undefined
No default extracted.
Shows the legend below the chart.
showTooltip: boolean | undefined
Default: true
Enables pointer, touch and arrow-key exploration. Defaults to true.
interactionLabel: string | undefined
No default extracted.
Localized instructions for keyboard exploration.
valueFormatter: ((value: number) => string) | undefined
No default extracted.
Formats values in the axis, value labels, legend and data table.
emptyLabel: string | undefined
No default extracted.
Text announced when there is nothing to draw.
onChange: ChangeEventHandler<HTMLDivElement, Element> | undefined
No default extracted.
Standard React/HTML attribute.
defaultValue: string | number | readonly string[] | undefined
No default extracted.
Standard React/HTML attribute.
className: string | undefined
No default extracted.
Standard React/HTML attribute.
style: CSSProperties | undefined
No default extracted.
Standard React/HTML attribute.
aria-label: string | undefined
No default extracted.
Defines a string value that labels the current element.
onClick: MouseEventHandler<HTMLDivElement> | undefined
No default extracted.
Standard React/HTML attribute.

Accessibility

Give the chart a descriptive aria-label including its units. A hidden data table provides the individual observations.
One Tab stop enters exploration. Arrow keys move between observations, Home/End jump, and Escape closes the tooltip while keeping focus.

Read the accessibility guide →

Preview

More examples

Grouped comparisons

Stacked totals

Horizontal categories

Named-part customization

Usage

API reference

PimoluChartDatum

PimoluChartSeries

PimoluBarChartProps

Accessibility

Related components