> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<CodeGroup>
  ```shell npm theme={null}
  npm install @graphysdk/react
  ```

  ```shell pnpm theme={null}
  pnpm add @graphysdk/react
  ```

  ```shell yarn theme={null}
  yarn add @graphysdk/react
  ```

  ```shell bun theme={null}
  bun add @graphysdk/react
  ```
</CodeGroup>

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](#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`.

```tsx theme={null}
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 spec={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:

```tsx theme={null}
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.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:

```tsx theme={null}
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' })],
  })
);
```

Because it sits on the spec, the stylesheet serializes and travels with the chart. See [Styling](/sdk-next/config/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:

```tsx theme={null}
<GraphProvider
  spec={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, maxAnimatedGeoms }`) to tune each; `intro` accepts `enabled`, `trigger`, `durationScale`, `stagger` and `staggerOrder`. A reduced-motion preference disables animation regardless.
* `showTooltips` — `true` by default.
* `slots` — per-region component overrides. See [Slots](/sdk-next/extending/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:

```shell theme={null}
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:

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

### Next steps

* Understand [how a chart is built](/sdk-next/concepts/how-a-chart-is-built) — the spec pipeline and the compile → render model
* Learn the [data structure](/sdk-next/data-structure) and how mappings reference columns
* Work through the [core concepts](/sdk-next/concepts/mappings) — mappings, geoms, scales, coords
* Browse the [chart types](/sdk-next/graph-types/index) and build a [line chart](/sdk-next/graph-types/line) end to end
* Read [licence and evaluation](/licence/evaluation) before you put a chart on a public page


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.