Docs

Introduction

19 chart types and 27 dashboard blocks for React and shadcn. The CLI copies each one into your project as TypeScript you own: no runtime package, no account.

What you get

Every chart takes the same shared props (header, states, legend, tooltip, formatting, motion and selection) and follows your shadcn theme. Blocks are whole dashboard cards: a chart, stats worked out from your rows, and a sentence that says what it shows. Start with Installation, or open a component:

Instrument, the theme you see everywhere, is free and MIT. Riso and Clay restyle every chart and block with the same props: changing theme changes an import path and nothing else.

Recharts or ECharts

Both builds of a chart draw the same marks from the same model, so the numbers, takeaway, table, keyboard behaviour and selection are identical. Switching is one import path. Choose Recharts for a smaller bundle and native Recharts children. Choose ECharts when you already use it, or for many marks: it draws on a canvas. Both builds still compute every row, so for tens of thousands of rows, aggregate or window the data first (the brush helps).

  • Recharts: pass Recharts children (ReferenceArea, Label, Customized) and they render inside the chart with your original rows. The Sankey draws its own layout.
  • ECharts: option is deep-merged over the generated option, or pass a function that receives it. onReady hands you the instance.
  • No engine: the heatmap, KPI stat and gauge are plain SVG by default. The heatmap also has an ECharts build for large grids (see Installation).
"use client";

import { BarChart } from "@/components/beautiful-charts/themes/instrument/echarts/bar-chart";

const data = [{ month: "Jan", orders: 186 }, { month: "Feb", orders: 305 }, { month: "Mar", orders: 237 }];

export function EChartsEscapeHatch() {
  return (
    <BarChart
      data={data}
      xKey="month"
      renderer="svg"
      // Deep-merged: this changes one axis setting and keeps everything else Instrument generated.
      option={{ yAxis: { splitNumber: 3 } }}
      onReady={(chart) => chart.on("click", (event) => console.log(event))}
    />
  );
}

Missing and odd data

The charts never invent data. Each case below is shown for what it is and named in a note under the chart, and the data table keeps every row.

  • null, undefined and NaN are missing, never zero. Lines break, bars are left out, and a line joins across gaps only if you set connectNulls on that series.
  • Percent stacks split each row by its absolute total, so negative parts are shown below zero rather than cancelled out.
  • Donuts leave out negative and missing values. groupBelow folds small segments into one “Other” segment, which lists its members.
  • Radial rings over their maximum fill the ring, carry a mark and keep their true number. Gauges pin out-of-range readings to the end of the scale the same way.
  • A Sankey with a link to an unknown node, a duplicate id or a cycle shows a plain message instead of a wrong diagram.
  • A KPI change from a zero base is shown as an amount, never as an infinite percentage. A block with no rows shows a dash for every stat.

Loading, empty, error

loading shows a skeleton the size of the chart. Over existing data it dims the old marks instead of removing them, so a refresh doesn't flash. An empty data array shows the empty state, and error shows the error state. Replace any of them with loadingState, emptyState or errorState. The card keeps its height in every state.

Controlled state

Each piece of interaction state can be left to the chart, given an initial value, or controlled by you: selected (a pinned row), selectedSeries, hidden (legend toggles), activeIndex (hover and focus), and on cartesian charts the brush range. Indexes always point into the data you passed, even when a brush shows a subset. Selections report their source: pointer, keyboard or table.

"use client";

import { useState } from "react";
import { LineChart } from "@/components/beautiful-charts/themes/instrument/recharts/line-chart";
import { BarChart } from "@/components/beautiful-charts/themes/instrument/recharts/bar-chart";

type Row = { day: string; orders: number; returns: number };

// Two charts on one cursor: hovering either moves both, and hiding a series in one legend hides it in both.
export function SyncedCharts({ rows }: { rows: Row[] }) {
  const [active, setActive] = useState<number | null>(null);
  const [hidden, setHidden] = useState<string[]>([]);
  const shared = { data: rows, xKey: "day" as const, activeIndex: active, onActiveChange: setActive, hidden, onHiddenChange: setHidden };
  return (
    <div className="grid gap-4 md:grid-cols-2">
      <LineChart {...shared} title="Orders and returns" />
      <BarChart {...shared} title="Returns" series={["returns"]} />
    </div>
  );
}

Tooltip content

tooltip.content replaces the body and keeps the frame, positioning and accessibility. It receives the row, its index and every visible series with its raw value (null when missing), its share in 100% stacks and its colour. Set position: "fixed" to pin it to a corner, or tooltip={false} to turn it off.

"use client";

import { BarChart } from "@/components/beautiful-charts/themes/instrument/recharts/bar-chart";

const data = [{ month: "Jan", desktop: 186, mobile: 80 }, { month: "Feb", desktop: 305, mobile: null }];

export function CustomTooltip() {
  return (
    <BarChart
      data={data}
      xKey="month"
      tooltip={{
        indicator: "line",
        content: ({ datum, series }) => (
          <div>
            <strong>{datum.month}</strong>
            {series.map((s) => <div key={s.key}>{s.label}: {s.value ?? "no data"}</div>)}
          </div>
        ),
      }}
    />
  );
}

Keyboard and screen readers

Each chart is one tab stop. Screen readers hear a summary computed from the data (replace it with ariaDescription). As you move, each point is announced in words: its category, series, value and, where it applies, its share.

  • ← → move between categories in the direction they're drawn, also on right-to-left pages.
  • ↑ ↓ move between series when there are several (rows, on a heatmap), otherwise between categories.
  • Home / End jump to the first or last category. Page Up / Page Down move by a larger step.
  • Enter or Space pins the current point. Escape clears it.

“Show data table” opens a real table of every value, and its rows select points too. Colour is never the only signal: forecasts are hatched or dashed, and deltas say “up” or “down” in words. The KPI stat is read as one sentence and the gauge is a meter, so neither takes focus.

Recipes

Each recipe is a complete client module, type-checked against the current source on every build.

Currency and locale

"use client";

import { AreaChart } from "@/components/beautiful-charts/themes/instrument/recharts/area-chart";

const data = [{ month: "2026-01", revenue: 18250 }, { month: "2026-02", revenue: 21400 }, { month: "2026-03", revenue: 19800 }];
const euros = new Intl.NumberFormat("de-DE", { style: "currency", currency: "EUR", maximumFractionDigits: 0 });

// Currency and locale: one formatter drives the axis, tooltip, table, readout and screen-reader text.
export function RevenueInEuros() {
  return (
    <AreaChart
      data={data}
      xKey="month"
      locale="de-DE"
      title="Umsatz"
      valueFormatter={(value) => euros.format(value)}
      xAxis={{ tickFormatter: (month) => String(month).slice(5) }}
    />
  );
}

A quiet dashboard tile

"use client";

import { LineChart } from "@/components/beautiful-charts/themes/instrument/recharts/line-chart";

const data = [{ day: "Mon", users: 120 }, { day: "Tue", users: 132 }, { day: "Wed", users: 128 }, { day: "Thu", users: 151 }];

// A quiet dashboard tile: compact, no axes or grid, no legend or table disclosure, subtle motion.
export function UsersTile() {
  return (
    <LineChart
      data={data}
      xKey="day"
      title="Daily users"
      density="compact"
      height={120}
      grid={false}
      xAxis={{ show: false }}
      yAxis={{ show: false }}
      legend={false}
      table={false}
      motion="subtle"
    />
  );
}

A 100% stack with a forecast

"use client";

import { BarChart } from "@/components/beautiful-charts/themes/instrument/recharts/bar-chart";

const data = [
  { quarter: "Q1", new: 40, expansion: 25 }, { quarter: "Q2", new: 44, expansion: 31 },
  { quarter: "Q3", new: 39, expansion: 38 }, { quarter: "Q4", new: 47, expansion: 41 },
];

// A 100% stack where the last quarter is a forecast: its bars are hatched, and the table says so.
export function RevenueMix() {
  return <BarChart data={data} xKey="quarter" title="Revenue mix" stack="percent" forecastFrom={3} />;
}

Refreshing without a flash

"use client";

import { BarChart } from "@/components/beautiful-charts/themes/instrument/recharts/bar-chart";

type Row = { region: string; orders: number };

// Data from your own fetching: during a refresh the old bars stay, dimmed, instead of flashing empty.
export function OrdersByRegion({ rows, isFetching, error }: { rows: Row[]; isFetching: boolean; error: Error | null }) {
  return (
    <BarChart
      data={rows}
      xKey="region"
      orientation="horizontal"
      title="Orders by region"
      loading={isFetching}
      error={error ? "Orders couldn't be loaded. Try again in a moment." : null}
    />
  );
}