Charts / Categorical

Bar Chart

Compare values across categories with accessible interactions, responsive layouts, and useful production states built in.

Type-safe
Keyboard accessible
Responsive
Copy-paste ready

Install Bar Chart

npx mario-charts@latest add bar-chart

Playground

Start with the default, then adjust only what your data needs.

Monthly revenue

January–June · USD

Waiting for chart space

Hover or tap to inspect. Use Tab, then arrow keys to move between bars.

tsx

import { BarChart } from "@/components/charts/bar-chart";

const data = [
  { month: "Jan", revenue: 4500 },
  { month: "Feb", revenue: 5200 },
  { month: "Mar", revenue: 4800 },
  { month: "Apr", revenue: 6100 },
];

export function RevenueChart() {
  return (
    <BarChart
      data={data}
      x="month"
      y="revenue"
      showGrid
    />
  );
}

Resilient by default

Built-in states preserve context when the data is not ready to render.

Loading
Keeps the chart frame stable while data is being resolved.
loading={true}
Error
Replaces the plot with an actionable message without shifting the layout.
error="Could not load data"
Empty
Explains that no values are available instead of rendering an empty plot.
data={[]}

Real data, predictable behavior

Positive and negative values share a zero baseline. Zero remains inspectable; missing values never become zero.

Pass finite numbers whenever possible. Numeric strings such as "1,250.50", "$1,250", and "15%" are accepted (15% means 15 percentage points). Empty, missing, infinite, or ambiguous values display an error identifying the row and key. Normalize localized numbers before plotting.

valueFormatter controls tooltip, value-label, and accessible text. Use axisValueFormatter for compact ticks. Custom tooltip payloads retain numeric values and the original row.

Switch the state above from Loading, Error, or Empty back to Ready: the chart keeps its frame and recovers without a remount. Arrow keys inspect every bar in either visual variant; Enter or Space activates a selectable bar, and Escape closes its tooltip.

tsx

const currency = new Intl.NumberFormat("en-US", {
  style: "currency", currency: "USD", maximumFractionDigits: 0,
});

<BarChart
  data={[{ month: "Jan", net: 4500 }, { month: "Feb", net: -2200 }]}
  x="month"
  y="net"
  valueFormatter={currency.format}
  ariaLabel="Net change by month"
  description="Amounts in US dollars."
  showGrid
/>

Choose the right orientation

The shape of the labels should decide the layout.

Vertical

Best for short category labels and chronological comparison.

Horizontal

Best for long labels, rankings, and dense category lists.

API Reference

The core surface stays small; advanced behavior remains explicit.

Prop	Type	Default	Description
`data`Required	readonly T[]	—	Data objects rendered by the chart.
`x`Required	keyof T	—	Property used for category labels.
`y`	keyof T	"value"	Property used for numeric values.
`colors`	readonly string[]	chart palette	Colors applied to bars in order.
`variant`	"filled" \| "outline"	"filled"	Visual treatment for each bar.
`orientation`	"vertical" \| "horizontal"	"vertical"	Direction in which bars grow.
`height`	number	300	Chart height in pixels.
`showGrid`	boolean	false	Displays grid lines and value ticks.
`animation`	boolean	true	Enables the entrance animation.
`loading`	boolean	false	Displays the loading state.
`error`	string \| null	null	Displays an actionable error state.
`showValues`	boolean	false	Shows formatted values on the plot.
`gridStyle`	"solid" \| "dashed" \| "dotted"	"dashed"	Grid line treatment.
`className`	string	—	Classes on the persistent chart frame, including loading/error/empty states.
`valueFormatter`	(value: number) => string	—	Formats inspection, value labels, accessible values, and ticks by default.
`axisValueFormatter`	(value: number) => string	—	Optional compact formatter for axis ticks.
`ariaLabel`	string	—	Accessible chart name.
`description`	string	—	Additional chart context, units, or interpretation.
`tooltipRenderer`	(data: BarChartTooltipData<T>) => ReactNode	—	Presentational custom tooltip. Receives numeric value, raw value, original row, label, color, and index.
`onBarClick`	(data: T, index: number) => void	—	Runs when a bar is selected.