Quickstart

Start with @graphysdk/react. One package builds the spec and renders the chart. The “Made with Graphy” mark is on by default.

1. Install the package

npm install @graphysdk/react

pnpm add @graphysdk/react

yarn add @graphysdk/react

bun add @graphysdk/react

What the install expects from your project:

React 19 — react@^19.0.0 is a peer of the package.
Nothing else for a read-only chart — the editing surface’s rich-text editor is an optional peer, so a chart you only paint pulls in no @tiptap/* package. See Editing.
moduleResolution: "bundler" (or node16 / nodenext) in your tsconfig.json — the packages ship an exports map, which moduleResolution: "node" skips.
A bundler that processes CSS imports from node_modules — Vite, Next.js and webpack with css-loader all do. There is no stylesheet to import: each entry point imports its own CSS file.
A client component — the components use the DOM. In the Next.js app router, put 'use client' at the top of the file that renders them.

2. Render your first chart

A chart needs three things: your data, a spec that says how to draw it, and the React components that paint it. All come from @graphysdk/react.

import { useMemo } from 'react';
import {
  GraphProvider,
  GraphRenderer,
  createSpec,
  pipe,
  geom,
  scale,
} from '@graphysdk/react';

// 1. Your data — a table of columns and rows.
const data = {
  columns: [
    { key: 'month', label: 'Month' },
    { key: 'revenue', label: 'Revenue' },
  ],
  rows: [
    { month: 'Jan', revenue: 12000 },
    { month: 'Feb', revenue: 15000 },
    { month: 'Mar', revenue: 18000 },
    { month: 'Apr', revenue: 17000 },
    { month: 'May', revenue: 21000 },
  ],
};

export function App() {
  // 2. The spec — map columns to aesthetics, pick a geom, declare the scales.
  const spec = useMemo(
    () =>
      pipe(
        createSpec({ x: 'month', y: 'revenue' }),
        geom.line(),
        scale.x(),
        scale.y()
      ),
    []
  );

  // 3. Render it.
  return (
    <div style={{ height: 320 }}>
      <GraphProvider spec={spec} data={data}>
        <GraphRenderer />
      </GraphProvider>
    </div>
  );
}

GraphRenderer fills its parent, so the parent needs a height. A container with no height paints nothing and logs ZERO_SIZE_CONTAINER once. Build the spec once or memoize it: a new spec object recompiles the chart.

3. Customize the chart

The chart’s chrome — titles, axes, legend, layout — lives in config. Pipe a config(...) item onto the spec:

import { createSpec, pipe, geom, scale, config } from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue', color: 'product' }),
  geom.line({ params: { curve: 'smooth' } }),
  scale.x(),
  scale.y.continuous({ domainMin: 0, nice: true }),
  scale.color.discrete(),
  config({
    content: {
      title: 'Monthly revenue',
      showTitle: true,
      subtitle: 'By product, 2026',
      showSubtitle: true,
    },
    axes: {
      y: { label: 'Revenue (£)' },
    },
    legend: { position: 'bottom' },
  })
);

4. Restyle it

Paint — colors, stroke widths, corner rounding, fonts — lives in a stylesheet on the spec. Pipe a styles(...) item in the same way. Redefining a built-in token restyles every default that reads it; a style.* entry targets one thing:

import { createSpec, pipe, geom, scale, styles, style } from '@graphysdk/react';

const spec = pipe(
  createSpec({ x: 'month', y: 'revenue' }),
  geom.bar(),
  scale.x(),
  scale.y(),
  styles({
    tokens: { geom: { light: '#0B5FFF', dark: '#6AA1FF' } },
    defaults: [style.geom.bar({ cornerRadius: 'full' })],
  })
);

The stylesheet sits on the spec, so it serializes and travels with the chart. See Styling for every target and the cascade that resolves them.

5. Color scheme and locale

GraphProvider accepts a colorScheme ('light' or 'dark', defaulting to 'light') and a formattingLocale ('en-GB', 'en-US', 'pt-PT' or 'ar') for number, date and currency formatting:

<GraphProvider
  spec={spec}
  data={data}
  colorScheme="dark"
  formattingLocale="en-GB"
>
  <GraphRenderer sizing={{ mode: 'responsive' }} />
</GraphProvider>

The provider’s other props:

theme — a theme that sits under the spec’s own styles and config. A theme’s colorScheme overrides the prop.
plugins — custom geoms, stats and transforms. See Extending.
onError, onWarnings — called with a compile’s errors or warnings. Both also go to the console, and a failed compile shows its errors in place of the chart.
onSpecChange, handleRef — for editing and driving the chart from outside the tree. See Provider and renderer.

theme and plugins are read once at mount; change the React key to swap them. data, spec and colorScheme recompile on every change. GraphRenderer has props of its own:

sizing — how the chart takes space. responsive (the default) fills its container; fixed takes a width and height; keepAspectRatio scales to the container width from intrinsicWidth and intrinsicHeight, or either one plus an aspectRatio.
onResize — called with the container size whenever it changes, in every sizing mode.
animation — true by default. false turns off the intro and the data transitions. An object { intro, transitions, maxAnimatedGeoms } tunes each; intro takes enabled, trigger ('mount' or 'inView'), durationScale, stagger and staggerOrder. A reduced-motion preference turns animation off regardless, as does a chart with more than maxAnimatedGeoms geoms (default 1500).
showTooltips — true by default. false hides the tooltip whatever config.tooltip says.
mode — 'readonly' (the default), 'editable' or 'point-and-edit'. The editing modes need EditableGraphRenderer from @graphysdk/react/editable.
slots — per-region component overrides. See Slots.

Editing

@graphysdk/react/editable exports EditableGraphRenderer. It mounts inside the GraphProvider from the main entry and adds a rich-text editor over the chart’s title, caption and text annotations. The editor is built on TipTap v3. Those packages are optional peers, so a read-only install skips them. Add them yourself when you import this entry:

npm install @tiptap/core @tiptap/pm @tiptap/react @tiptap/extensions \
  @tiptap/extension-bold @tiptap/extension-document @tiptap/extension-hard-break \
  @tiptap/extension-heading @tiptap/extension-italic @tiptap/extension-link \
  @tiptap/extension-paragraph @tiptap/extension-text @tiptap/extension-text-align \
  @tiptap/extension-text-style @tiptap/extension-underline

Using the engine and renderer separately

@graphysdk/react-renderer exports the same GraphProvider and GraphRenderer with the mark off by default. @graphysdk/viz-engine holds the builders and the compiler, with no React. Import them directly when you want the mark off or you are not in React:

import { createSpec, pipe, geom, scale } from '@graphysdk/viz-engine';
import { GraphProvider, GraphRenderer } from '@graphysdk/react-renderer';

A spec that sets config.content.brandMark.enabled keeps that setting in every package.

Next steps

Understand how a chart is built — the spec pipeline and the compile → render model
Learn the data structure and how mappings reference columns
Work through the core concepts — mappings, geoms, scales, coords
Browse the chart types and build a line chart end to end
Read license and evaluation before you put a chart on a public page

Get Started

Core concepts

Chart types

Themes

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

1. Install the package

2. Render your first chart

3. Customize the chart

4. Restyle it

5. Color scheme and locale

Editing

Using the engine and renderer separately

Next steps

​1. Install the package

​2. Render your first chart

​3. Customize the chart

​4. Restyle it

​5. Color scheme and locale

​Editing

​Using the engine and renderer separately

​Next steps

1. Install the package

2. Render your first chart

3. Customize the chart

4. Restyle it

5. Color scheme and locale

Editing

Using the engine and renderer separately

Next steps