React Chart component

Preview

<div style={{ width: '100%', height: 300 }}>
  <ChartContainer
    aria-label="Revenue and target by month"
    config={{
      revenue: { label: 'Revenue', series: 1 },
      target: { label: 'Target', series: 6 },

Usage

Use when

A trend over time is the point
Categories need comparing side by side
A whole splits into parts worth seeing

Avoid when

One number tells the story (use Text or Badge)
Distance to a goal (use Progress)
Readers need exact values (use Table)

Implementation notes

Wrap every recharts chart in ChartContainer
Map each data key to a label and a series index; draw the series with var(--fui-chart-N)
Never colour a series with a status hue — status colours mean status
Pair with ChartTooltip and ChartLegend rather than recharts' own
Give the container a real height — recharts cannot measure zero; loading, empty and error keep that height
A failed load passes error with words that say what to do and onRetry for the way out; an empty chart passes empty, emptyDescription and one emptyAction

Installation

pnpm add @usefragments/ui

The npm package stays managed by your package manager. Import styles once from @usefragments/ui/styles. See the installation guide for framework and theme setup.

Additional packages

recharts — Optional — powers Chart.Tooltip and Chart.Legend. Without it the container shows the data table, or a 'Chart unavailable' state.

pnpm add recharts

Anatomy

Import Chart once, then compose its parts with dot notation.

Chart.Tooltip
Chart.TooltipContent
Chart.Legend
Chart.LegendContent
Chart.preload

Examples

Bar Chart

Fixed categories, compared by height — the safest default.

<div style={{ width: '100%', height: 300 }}>
  <ChartContainer
    aria-label="Sessions by device"
    config={{ sessions: { label: 'Sessions', series: 1 } }}
  >
    <BarChart data={deviceData}>

Area Chart

The fill under the line stresses volume, not just direction.

<div style={{ width: '100%', height: 300 }}>
  <ChartContainer
    aria-label="Revenue by month"
    config={{ revenue: { label: 'Revenue', series: 3 } }}
  >
    <AreaChart data={monthlyData}>

States

Loading, empty and error stay in the chart's own box.

import { type ChartConfig } from "@usefragments/ui";

const config: ChartConfig = { revenue: { label: "Revenue", series: 1 } };
const data = [{ month: "Jan", revenue: 4200 }, { month: "Feb", revenue: 4800 }];

<>

API reference

Component props
Prop	Type	Default	Description
`Chart.Legend.content`	`React.ReactNode \| ((legendProps: Record<string, unknown>) => React.ReactNode)`	Not set	—
`Chart.LegendContent.payload`	`readonly (ChartPayloadEntry & { value?: string; })[] \| undefined`	Not set	—
`Chart.Tooltip.content`	`React.ReactNode \| ((tooltipProps: Record<string, unknown>) => React.ReactNode)`	Not set	—
`Chart.Tooltip.hideLabel`	`boolean \| undefined`	Not set	—
`Chart.Tooltip.labelFormatter`	`((label: string, payload: ChartTooltipContentProps["payload"]) => React.ReactNode) \| undefined`	Not set	—
`Chart.Tooltip.valueFormatter`	`((value: number \| string) => string) \| undefined`	Not set	—
`Chart.TooltipContent.active`	`boolean \| undefined`	Not set	—
`Chart.TooltipContent.hideLabel`	`boolean \| undefined`	Not set	—
`Chart.TooltipContent.label`	`string \| undefined`	Not set	—
`Chart.TooltipContent.labelFormatter`	`((label: string, payload: ChartTooltipContentProps["payload"]) => React.ReactNode) \| undefined`	Not set	—
`Chart.TooltipContent.payload`	`readonly ChartPayloadEntry[] \| undefined`	Not set	—
`Chart.TooltipContent.valueFormatter`	`((value: number \| string) => string) \| undefined`	Not set	—
`children`Required	`React.ReactElement<unknown, string \| React.JSXElementConstructor<any>>`	Not set	A recharts chart component (LineChart, BarChart, etc.)
`config`Required	`ChartConfig`	Not set	ChartConfig mapping each data key to a label and a series index 1–6 (reads --fui-chart-N), with an optional legend icon
`dataTable`	`React.ReactNode`	Not set	Accessible data table or textual fallback; shown visibly when recharts is missing
`empty`	`React.ReactNode`	`"No data to show"`	The empty state's title, shown when the chart child's data is an empty array
`emptyAction`	`React.ReactNode`	Not set	The empty state's one way forward (a Button)
`emptyDescription`	`React.ReactNode`	Not set	The empty state's copy under the title: why there is nothing yet
`error`	`React.ReactNode`	Not set	When set, replaces the chart with an error box (danger glyph, this message, retry)
`loading`	`boolean \| undefined`	`false`	Draws a skeleton at the chart's height while the data loads
`onRetry`	`(() => void) \| undefined`	Not set	Retry the failed load; shows a retry button in the error box
`retryLabel`	`string \| undefined`	`Retry`	Label for the retry button
`summary`	`string \| undefined`	Not set	Non-visual summary announced to assistive technology users
`style`	`CSSProperties \| undefined`	Not set	—

Accessibility

The frame is role img with an aria-label; pass summary for the takeaway
ChartConfig labels are what the tooltip and legend read
Pass dataTable to offer the same numbers as text
Loading sets aria-busy; empty and error render as a labelled group with words, not colour; the error box is an alert

CardparentCharts are typically placed inside Cards
ProgressalternativeUse Progress for single-value completion
TablesiblingCombine with Table for full data views

Next steps

Accessibility guidanceThe keyboard, focus and naming rules every component carries.
Every componentThe catalog, grouped by what each component does.