01 · Start here

Install Generative Charts

npm install generative-charts

Import the stylesheet once near your application root, then import chart components directly from the package.

import { LineChart } from "generative-charts";
import "generative-charts/styles.css";

const data = [
  { month: "Jan", revenue: 42 },
  { month: "Feb", revenue: 58 },
  { month: "Mar", revenue: 51 },
];

<LineChart
  data={data}
  xKey="month"
  series={[{ dataKey: "revenue", label: "Revenue" }]}
  theme="mono-editorial"
  appearance="light"
  title="Monthly revenue"
/>

02 · Data contracts

Objects in, chart out.

Cartesian charts accept an array of ordinary objects, one key for the horizontal category or value, and a typed series array. Pie charts use name and value keys. Heatmaps and terrain use three keyed dimensions.

type Series<T> = {
  dataKey: keyof T;
  label: string;
  color?: string;
};

Numeric strings are accepted. Missing measurements are omitted, break line and area paths, or render as explicit missing cells instead of silently becoming zero. Use missingValueStrategy when connecting gaps or zero imputation is intentional, and onDiagnostic to observe structured data-quality warnings.

<LineChart
  data={events}
  xKey="timestamp"
  series={series}
  missingValueStrategy="gap"
  xScale={{ type: "time", timeZone: "UTC", tickCount: 5 }}
  onDiagnostic={(diagnostic) => report(diagnostic)}
/>

If no usable values remain, the component renders an accessible empty state.

03 · Components

Eighteen useful families.

Cohort retention

<CohortChart
  data={retention}
  cohortKey="cohort"
  periodKey="period"
  valueKey="retained"
  sizeKey="users"
/>

Bar variations

<BarChart variant="horizontal" layout="grouped" ... />
<BarChart variant="vertical" layout="stacked" ... />

// Signed values automatically diverge from zero.
<BarChart data={[{ label: "Growth", change: 24 }, { label: "Churn", change: -11 }]} categoryKey="label" series={[{ dataKey: "change", label: "MRR change" }]} />

Line and area variations

<LineChart curve="linear" showPoints={false} ... />
<AreaChart curve="smooth" stacked ... />

Pie and donut

<PieChart variant="donut" centerLabel="100%" ... />
<PieChart variant="extruded" ... />

3D terrain

<TerrainChart data={data} xKey="x" zKey="z" valueKey="elevation" density="medium" />

04 · Themes

Three themes. Two modes.

Generative Charts ships Mono Editorial, Neon Instruments, and Airform. The universal appearance prop switches any theme between light and dark without changing its visual identity.

import { createTheme } from "generative-charts";

<LineChart theme="neon-instruments" appearance="dark" ... />

const brandTheme = createTheme("mono-editorial", {
  id: "acme",
  name: "Acme",
  light: { palette: ["#5b5bd6", "#29a37a"] },
  dark: { palette: ["#a5b4fc", "#6ee7b7"] },
});

Theme variables are scoped to each chart figure. Generative Charts never changes global colors or typography.

05 · Reference

Shared props

06 · Behavior

Responsive and server-safe.

Charts measure the available plot container—not the browser viewport—and switch between compact, standard, and wide layout grammar. Tick count, category density, label wrapping, legend spacing, and source treatment respond together while height remains explicit. IDs come from React’s stable useId API, and temporal ticks use deterministic UTC formatting by default.

Legends

When more than one series is present, legend controls can hide and restore individual series. Domains and geometry update from the remaining visible series.

Animation

Marks enter with a short stagger. Set animate={false} to disable it. The stylesheet automatically removes transitions for reduced-motion users.

07 · Accessibility

Readable in more than one way.

• Every SVG receives a programmatic title and description.
• Line, area, and combo comparisons expose one roving tab stop; Left/Right moves by x value and Up/Down changes the active series.
• Shared tooltips list every visible series at the current pointer, touch, or keyboard position.
• Enter or Space activates the active datum and series.
• Legends use pressed-state buttons instead of color-only controls.
• Semantic chart text never drops below 12px.
• Empty datasets produce a visible and announced status.

08 · Help

Troubleshooting

The chart has no styles

Import generative-charts/styles.css once in your root layout or application entry point.

The chart shows an empty state

Confirm that your series keys exist and contain at least one finite numeric value.

The chart is too short

Pass a larger height. Width always follows the containing element.