Quickstart

Start with @graphysdk/react. One package builds the spec and renders the chart. The “Powered by 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

A few things 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 rich-text editor behind the editing surface is an optional peer, so a chart you only paint pulls in no @tiptap/* package. See Editing if you mount one.
moduleResolution: "bundler" (or node16 / nodenext) in your tsconfig.json — the packages ship an exports map, which the legacy "node" resolution 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 injects its own CSS.

2. Render your first chart

A chart needs three things: your data, a spec describing how to draw it, and the React surface to paint it — all 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 (
    <GraphProvider input={spec} data={data}>
      <GraphRenderer />
    </GraphProvider>
  );
}

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: { interpolate: 'catmull-rom' } }),
  scale.x(),
  scale.y.continuous({ domainMin: 0, nice: true }),
  scale.color.palette(),
  config({
    content: {
      title: 'Monthly revenue',
      isTitleVisible: true,
      subtitle: 'By product, 2026',
      isSubtitleVisible: 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: { geomColor: { light: '#0B5FFF', dark: '#6AA1FF' } },
    defaults: [style.geom.bar({ borderRadius: 'full' })],
  })
);

Because it sits on the spec, the stylesheet serializes and travels with the chart. See Styling for the full set of targets and the cascade that resolves them.

5. Color scheme and locale

GraphProvider accepts a colorScheme ('light' or 'dark', defaulting to 'light') and a formattingLocale for number, date and currency formatting:

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

GraphRenderer takes a handful of props of its own:

sizing — how the chart claims space. responsive fills its container, fixed takes explicit width/height, and keepAspectRatio scales to the container width from an intrinsicWidth + intrinsicHeight (or either one plus an aspectRatio).
animation — true by default. Pass false to turn intro and transition animation off, or an object ({ intro, transitions }) to tune each; intro accepts enabled, durationScale, stagger, staggerOrder and maxAnimatedGeoms. A reduced-motion preference disables animation regardless.
showTooltips — true by default.
slots — per-region component overrides. See Slots.

Editing

@graphysdk/react/editable mounts a rich-text editor over the chart’s title, caption and text annotations, and it is built on TipTap v3. Those packages are declared as optional peers so a read-only install skips them; add them yourself when you import that 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

If you want the mark off, or you are not in React, import those packages yourself:

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

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 licence and evaluation before you put a chart on a public page

Get Started

Core concepts

Chart types

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