Getting Started

Render your first chart in under five minutes.

Install

pnpm add pixi-charts pixi.js
# or
npm install pixi-charts pixi.js
# or
yarn add pixi-charts pixi.js

pixi.js is a peer dependency — install it alongside the library so you control the exact PixiJS version your app uses. PixiJS v8 is ESM-only, and so is pixi-charts; this works out of the box with Vite, esbuild, Rollup, webpack 5+, Next.js, Astro, and any other modern bundler.

Your first chart

Every chart is described by a single ChartSpec value: declarative JSON that says what to render, not how. Pass it to render along with the DOM element that should host the chart.

import { render, type ChartSpec } from 'pixi-charts';

const spec: ChartSpec = {
  type: 'line',
  data: [
    { month: 'Jan', revenue: 12_400 },
    { month: 'Feb', revenue: 13_900 },
    { month: 'Mar', revenue: 15_200 },
    // …nine more months
  ],
  encoding: {
    x: { field: 'month', type: 'categorical' },
    y: { field: 'revenue', type: 'quantitative' },
  },
};

const container = document.getElementById('chart');
if (!container) throw new Error('Chart container #chart not found');
const chart = await render(spec, container);

// Later — e.g. when the component unmounts — clean up:
chart.destroy();

That spec, rendered live:

Understanding ChartSpec

A spec has four parts:

• type picks one of the six chart kinds: 'line', 'area', 'bar', 'scatter', 'heatmap', or 'pie' (see ChartType).
• data is an array of plain objects, one row per datum. No special shape required — bring whatever your API or CSV gives you.
• encoding binds object fields to visual channels — x, y, color, size, value — and tells the library which kind of scale to build ('quantitative', 'temporal', or 'categorical'). See ChartEncoding for the full shape.
• options (optional) is layout, legend, tooltip, and orientation knobs. animation (optional) controls the enter transition. See ChartOptions and AnimationOptions.

The same spec shape works across every chart type. That’s the point: charts are values, not imperative drawing routines. The library validates the spec up front with a zod schema and throws teaching-style errors when something’s off, so misshaped specs fail fast with a useful message. It also makes specs trivial to generate from an LLM, a config file, or a JSON-driven dashboard tool.

Switching chart types

Because the spec shape is unified, swapping type re-renders the same data as a different visualization — no other code changes. Here’s the same monthly-revenue data as a line and as a bar chart:

The only difference between those two specs is type: 'line' vs. type: 'bar'. Same data, same encoding, different chart.

Common patterns

Responsive resize

The chart sizes itself to the container’s clientWidth × clientHeight and re-renders on resize via ResizeObserver. Give the container a percentage width and the chart fills it:

const container = document.getElementById('chart');
if (!container) throw new Error('Chart container #chart not found');
container.style.width = '100%';
container.style.height = '400px';
await render(spec, container);

No manual resize wiring required.

Cleanup

The object returned by render() is a Chart instance. Call .destroy() on it when the chart is leaving the DOM — that cancels in-flight tweens, disconnects the ResizeObserver, destroys the PIXI Application, and removes the canvas. .destroy() is idempotent, so it’s safe to call more than once.

In a React component:

import { useLayoutEffect, useRef } from 'react';
import { render, type ChartSpec, type Chart } from 'pixi-charts';

export function MyChart({ spec }: { spec: ChartSpec }) {
  const containerRef = useRef<HTMLDivElement>(null);

  useLayoutEffect(() => {
    if (!containerRef.current) return;
    let chart: Chart | null = null;
    let cancelled = false;

    render(spec, containerRef.current).then((c) => {
      if (cancelled) c.destroy();
      else chart = c;
    });

    return () => {
      cancelled = true;
      chart?.destroy();
    };
  }, [spec]);

  return <div ref={containerRef} style={{ width: '100%', height: 400 }} />;
}

Validating a spec before rendering

If the spec comes from an external source (JSON config, a server response, an LLM), validate it before handing it to render(). validateChartSpec throws a ChartSpecValidationError with a teaching-format message that points at the offending field:

import { validateChartSpec, ChartSpecValidationError, render } from 'pixi-charts';

try {
  const spec = validateChartSpec(JSON.parse(jsonString));
  await render(spec, container);
} catch (err) {
  if (err instanceof ChartSpecValidationError) {
    // err.message lists every issue with its path, expected shape,
    // and (where useful) a minimal example
    console.error(err.message);
  } else {
    throw err;
  }
}

render() calls validateChartSpec internally, so this is only necessary if you want to surface validation errors yourself (e.g. to a config editor’s error panel).

What’s next

• Chart Gallery — every chart type with live examples and a per-chart encoding reference.
• Performance — the library remains interactive at 100k+ points where Canvas-based libraries stall. See the live numbers, and how it compares to Chart.js.
• API Reference — every type, every option, every method.