React Charts: examples and API

Preview

Live preview

Changes apply to this preview only.

Tasks completed this month data
Segment	Value	Share
Design	36	36%
Engineering	48	48%
Research	16	16%

Design36 · 36%
Engineering48 · 48%
Research16 · 16%

Loading the interactive example?

Width adapts to the available space

"use client";

import { useState } from "react";
import { Button, DonutChart } from "@pimolu/react";

export function ChartExample() {
  const [week, setWeek] = useState(false);
  const data = week
    ? [
      { label: "Design", value: 14 },
      {
        label: "Engineering",
        value: 20
      },
      {
        label: "Research",
        value: 6
      }
    ]
    : [
      {
        label: "Design",
        value: 36
      },
      {
        label: "Engineering",
        value: 48
      },
      {
        label: "Research",
        value: 16
      }
    ];
  return (
    <div className="space-y-5">
      <Button appearance="outline" onClick={() => setWeek(!week)}>Show {
        week
          ? "this month"
          : "this week"
      }</Button>
      <DonutChart
        aria-label={`Tasks completed ${week ? "this week" : "this month"}`}
        data={data}
        centerValue={week
          ? "40"
          : "100"}
        centerLabel="Tasks completed"
        width={240}
        height={240}
      />
    </div>
  );
}

More examples

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

Dashboard

A reporting view assembled from the five chart types. Each card keeps the chart label, legend and table inside the same component.

Open preview

Bar charts

Grouped and stacked series, plus a horizontal layout with value labels and axis titles.

Open preview

Line and area

Multiple series, optional points, grid lines, axis labels and a legend. AreaChart uses the same props with a filled area.

Open preview

Usage

The family exports BarChart, LineChart, AreaChart, DonutChart and Sparkline. Match data to each chart's contract and use valueFormatter for consistent values.

Chart width and height define a viewBox, not a fixed CSS pixel size. Keep labels legible at small widths; use a simpler Sparkline rather than shrinking a dense chart. Do not assume zoom or tooltip props that are absent from the API.

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.

PimoluChartBaseProps

Type source

PimoluChartBaseProps public API
Name	Type	Default	Description
`width`	`number \| undefined`	`640 (or 240 for the donut)`	viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
`height`	`number \| undefined`	`320 (or 240 for the donut)`	viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
`showLegend`	`boolean \| undefined`	—	Shows the legend below the chart.
`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.

width: number | undefined
Default: 640 (or 240 for the donut)
viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
height: number | undefined
Default: 320 (or 240 for the donut)
viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
showLegend: boolean | undefined
No default extracted.
Shows the legend below the chart.
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.

PimoluBarChartProps

Type source

PimoluBarChartProps public API
Name	Type	Default	Description
`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`	`640 (or 240 for the donut)`	viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
`height`	`number \| undefined`	`320 (or 240 for the donut)`	viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
`showLegend`	`boolean \| undefined`	—	Shows the legend below the chart.
`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.

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
Default: 640 (or 240 for the donut)
viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
height: number | undefined
Default: 320 (or 240 for the donut)
viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
showLegend: boolean | undefined
No default extracted.
Shows the legend below the chart.
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.

PimoluLineChartProps

Type source

PimoluLineChartProps public API
Name	Type	Default	Description
`series`Required	`PimoluChartSeries[]`	`[]`	One or more series to draw.
`labels`	`string[] \| undefined`	`"1", "2", ..`	Category labels. Defaults to "1", "2", ...
`max`	`number \| undefined`	—	Upper bound of the value axis. Derived from the data when omitted.
`showGrid`	`boolean \| undefined`	`true`	Shows horizontal grid lines. Defaults to true.
`showPoints`	`boolean \| undefined`	`false`	Shows a point for each value. Defaults to false.
`xAxisLabel`	`string \| undefined`	—	Optional title under the category axis.
`yAxisLabel`	`string \| undefined`	—	Optional title beside the value axis.
`width`	`number \| undefined`	`640 (or 240 for the donut)`	viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
`height`	`number \| undefined`	`320 (or 240 for the donut)`	viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
`showLegend`	`boolean \| undefined`	—	Shows the legend below the chart.
`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.

seriesRequired: PimoluChartSeries[]
Default: []
One or more series to draw.
labels: string[] | undefined
Default: "1", "2", ..
Category labels. Defaults to "1", "2", ...
max: number | undefined
No default extracted.
Upper bound of the value axis. Derived from the data when omitted.
showGrid: boolean | undefined
Default: true
Shows horizontal grid lines. Defaults to true.
showPoints: boolean | undefined
Default: false
Shows a point for each value. Defaults to false.
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
Default: 640 (or 240 for the donut)
viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
height: number | undefined
Default: 320 (or 240 for the donut)
viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
showLegend: boolean | undefined
No default extracted.
Shows the legend below the chart.
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.

PimoluAreaChartProps

Type source

PimoluAreaChartProps public API
Name	Type	Default	Description
`series`Required	`PimoluChartSeries[]`	`[]`	One or more series to draw.
`labels`	`string[] \| undefined`	`"1", "2", ..`	Category labels. Defaults to "1", "2", ...
`max`	`number \| undefined`	—	Upper bound of the value axis. Derived from the data when omitted.
`showGrid`	`boolean \| undefined`	`true`	Shows horizontal grid lines. Defaults to true.
`showPoints`	`boolean \| undefined`	`false`	Shows a point for each value. Defaults to false.
`xAxisLabel`	`string \| undefined`	—	Optional title under the category axis.
`yAxisLabel`	`string \| undefined`	—	Optional title beside the value axis.
`width`	`number \| undefined`	`640 (or 240 for the donut)`	viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
`height`	`number \| undefined`	`320 (or 240 for the donut)`	viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
`showLegend`	`boolean \| undefined`	—	Shows the legend below the chart.
`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.

seriesRequired: PimoluChartSeries[]
Default: []
One or more series to draw.
labels: string[] | undefined
Default: "1", "2", ..
Category labels. Defaults to "1", "2", ...
max: number | undefined
No default extracted.
Upper bound of the value axis. Derived from the data when omitted.
showGrid: boolean | undefined
Default: true
Shows horizontal grid lines. Defaults to true.
showPoints: boolean | undefined
Default: false
Shows a point for each value. Defaults to false.
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
Default: 640 (or 240 for the donut)
viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
height: number | undefined
Default: 320 (or 240 for the donut)
viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
showLegend: boolean | undefined
No default extracted.
Shows the legend below the chart.
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.

PimoluDonutChartProps

Type source

PimoluDonutChartProps public API
Name	Type	Default	Description
`data`Required	`PimoluChartDatum[]`	`[]`	Segments of the ring. Values are treated as positive weights.
`centerValue`	`string \| undefined`	—	Large text in the middle of the ring, for example a total.
`centerLabel`	`string \| undefined`	—	Small caption under the centre value.
`thickness`	`number \| undefined`	`28`	Ring thickness in viewBox units. Defaults to 28.
`width`	`number \| undefined`	`640 (or 240 for the donut)`	viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
`height`	`number \| undefined`	`320 (or 240 for the donut)`	viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
`showLegend`	`boolean \| undefined`	—	Shows the legend below the chart.
`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.

dataRequired: PimoluChartDatum[]
Default: []
Segments of the ring. Values are treated as positive weights.
centerValue: string | undefined
No default extracted.
Large text in the middle of the ring, for example a total.
centerLabel: string | undefined
No default extracted.
Small caption under the centre value.
thickness: number | undefined
Default: 28
Ring thickness in viewBox units. Defaults to 28.
width: number | undefined
Default: 640 (or 240 for the donut)
viewBox width. The rendered SVG is always fluid: its width is 100% of the container and its height follows the viewBox ratio. Defaults to 640 (or 240 for the donut).
height: number | undefined
Default: 320 (or 240 for the donut)
viewBox height. Also controls the aspect ratio of the chart. Defaults to 320 (or 240 for the donut).
showLegend: boolean | undefined
No default extracted.
Shows the legend below the chart.
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.

PimoluSparklineProps

Type source

PimoluSparklineProps public API
Name	Type	Default	Description
`data`Required	`number[]`	`[]`	Trend values, oldest first.
`area`	`boolean \| undefined`	`false`	Fills the area under the line. Defaults to false.
`color`	`string \| undefined`	—	Explicit line colour. Falls back to the primary token.
`width`	`number \| undefined`	`160`	viewBox width. Defaults to 160.
`height`	`number \| undefined`	`40`	viewBox height. Defaults to 40.
`valueFormatter`	`((value: number) => string) \| undefined`	—	Formats values in the hidden 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.

dataRequired: number[]
Default: []
Trend values, oldest first.
area: boolean | undefined
Default: false
Fills the area under the line. Defaults to false.
color: string | undefined
No default extracted.
Explicit line colour. Falls back to the primary token.
width: number | undefined
Default: 160
viewBox width. Defaults to 160.
height: number | undefined
Default: 40
viewBox height. Defaults to 40.
valueFormatter: ((value: number) => string) | undefined
No default extracted.
Formats values in the hidden 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 an aria-label that describes the dataset.
The charts include data tables for assistive technology. Keep labels and numeric context meaningful without relying only on color.

Read the accessibility guide →

Preview

More examples

Dashboard

Bar charts

Line and area

Usage

API reference

PimoluChartDatum

PimoluChartSeries

PimoluChartBaseProps

PimoluBarChartProps

PimoluLineChartProps

PimoluAreaChartProps

PimoluDonutChartProps

PimoluSparklineProps

Accessibility

Related components