Ballmac UI home

Chart

Theme-aware chart wrapper for Recharts with token colors, a styled tooltip and legend, a named figure with a screen-reader summary, and keyboard navigation.

6/6 checksv1.1.0Updated Oct 18, 2026Ships with a test
What changed
  1. 1.1.0 Oct 18, 2026Adds ChartCenterLabel and a `format` prop on ChartContainer, groups tooltip numbers by the locale (useLocale) and looks a series up by what `nameKey` points at first, which fixes pie legends. No prop was removed.

Update without losing your edits

Revenue

April to September

Revenue grew from $18,200 in April to $34,600 in September. Refunds stayed between $900 and $2,100.

Installation

$ pnpm dlx shadcn@latest add @ballmac/chart

Usage

import { ChartContainer, ChartTooltip, ChartTooltipContent, ChartLegend, ChartLegendContent, ChartCenterLabel, ChartStyle, useChart } from "@/components/ballmac/chart"

The full example is in the Code tab above.

Examples

Grouped bars

Web sessions peak on Tuesday at 305. Mobile peaks the same day at 200.

Donut

Search brings the most visitors (4,210), followed by direct (2,890), social (1,630) and email (980).

API reference

<ChartContext>

PropTypeDefault
config*ChartConfig—
format

Writes a value for the tooltip. Without it numbers use the locale's grouping.

(value: number, key: string) => string—

<ChartContainer>

PropTypeDefault
config*

Series definitions keyed by the chart's `dataKey`. Each becomes a `--color-<key>` CSS variable.

ChartConfig—
children*

One Recharts chart (AreaChart, BarChart, LineChart, PieChart, RadarChart…).

React.ComponentProps<typeof RechartsPrimitive.ResponsiveContainer>["children"]—
label*

Accessible name of the figure.

string—
summary

Plain-language summary of what the chart shows, read by screen readers.

string—
initialDimension

Size used before the container is measured, so the server render has a stable box.

{ width: number; height: number }{ width: 480, height: 270 }
format

Writes a value in the tooltip, for example `(v) => "$" + v`. The key is the series.

(value: number, key: string) => string—
width*number—
height*number—

<ChartTooltipContent>

PropTypeDefault
activeboolean—
payloadPayloadItem[]—
labelReact.ReactNode—
classNamestring—
indicator

Marker style before each value.

"dot" | "line" | "dashed""dot"
hideLabelbooleanfalse
hideIndicatorbooleanfalse
labelKey

Key in the data point whose value is used as the tooltip title.

string—
nameKey

Key used to look up the series name and color in `config`.

string—
labelFormatter(label: React.ReactNode, payload: PayloadItem[]) => React.ReactNode—
formatter(value: number | string, name: string, item: PayloadItem, index: number) => React.ReactNode—
labelClassNamestring—
colorstring—

<ChartCenterLabel>

PropTypeDefault
value*

The big text: a total, a percentage.

string—
label

The small text under it.

string—
cy

Where the ring's center sits, as a share of the plot height. A half ring (a gauge) has its center near the bottom, 0.88.

number0.5
classNamestring—

<ChartLegendContent>

PropTypeDefault
payloadArray<{ value?: string | number; dataKey?: string | number; color?: string; type?: string }>—
verticalAlign"top" | "middle" | "bottom""bottom"
hideIconbooleanfalse
nameKey

Key used to look up the series in `config`.

string—
valuestring | number—
dataKeystring | number—
colorstring—
typestring—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
Arrow keysMove between data points (accessibilityLayer)
Screen readersRead the figure name and summary

Quality scorecard

6/6

Every applicable check passes

Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.1.0, across 3 examples.

How we measure
  • Passed: Accessibility scan

    No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).

  • Passed: Small screens

    No sideways scrolling at 360, 390 or 1280 px wide.

  • Passed: Reduced motion

    No endless animation to begin with.

  • Not applicable: Right to left

    Not mirrored by design: Recharts draws its axes in SVG coordinates, which do not mirror.

  • Passed: Clean console

    No console errors or React hydration errors while loading.

  • Passed: Keyboard

    4 tab stops, each showing a visible change when it takes focus. 2 documented keys.

  • Not applicable: Loading, empty and error

    Does not show data or take submissions.

  • Passed: Automated tests

    Covered by chart.test.tsx.

  • For information: Footprint

    4.5 KB of source (gzip) in 1 file. Installs recharts.

Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.

Use with AI

Wrap any Recharts chart in ChartContainer with a config of label and color per series. Use ChartTooltipContent and ChartLegendContent. Always pass label and summary. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Chart (@ballmac/chart) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Dashboards and reports
  • Trends, comparisons and proportions

Not for

  • A tiny inline trend; use sparkline
  • A single ring value; use progress-ring

Registry JSON: https://ui.ballmac.com/r/chart.json

Credits

Based on shadcn/ui Chart, adapted by Ballmac. Free to use in personal and commercial projects.

Ballmac UI Pro

Need the whole screen, not one piece?

311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.

Not ready? Try three Pro blocks free

Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.