> ## 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.

# Provider & renderer

Every chart is a `<GraphProvider>` wrapping a `<GraphRenderer>`. The provider owns the data and spec and compiles them; the renderer paints the result.

```tsx theme={null}
import { GraphProvider, GraphRenderer } from '@graphysdk/react';

<GraphProvider spec={spec} data={data} colorScheme="light">
  <GraphRenderer sizing={{ mode: 'responsive' }} />
</GraphProvider>;
```

## GraphProvider

Holds the inputs and produces the scene. It recompiles when `spec`, `data`, `customPalettes` or `colorScheme` change by reference (a scheme change keeps layer ids, like a data change).

<ParamField path="data" type="Data" required>
  The [data table](/sdk-next/data-structure) the spec draws from.
</ParamField>

<ParamField path="spec" type="Spec" required>
  The chart to compile — a [spec](/sdk-next/concepts/how-a-chart-is-built) from
  `createSpec`/`pipe`.
</ParamField>

<ParamField path="colorScheme" type="ColorScheme" default="light">
  `'light'` or `'dark'`. Selects the base chrome token set, decides which
  half of every `{ light, dark }` [stylesheet](/sdk-next/config/styling) color
  and `token()` pair paints, and picks the tones of the default mono palette.
  See [Theming](/sdk-next/rendering/theming).
</ParamField>

<ParamField path="customPalettes" type="CustomPalettes">
  Host-owned palettes keyed by id — `Record<string, { id: string; hex: string;
      name?: string }[]>`. A `scale.color.palette({ palette: { type: 'custom', id }
      })` resolves against this map.
</ParamField>

<ParamField path="formattingLocale" type="Locale">
  Locale for formatting displayed values. See [Formatting &
  locale](/sdk-next/rendering/formatting).
</ParamField>

<ParamField path="onError" type="(errors: VizDiagnostic[]) => void">
  Fires with the diagnostics whenever a compile, recompile or dispatch produces
  errors, and again for a render-time throw caught by the error boundary. The
  chart renders an error panel in place rather than blanking.
</ParamField>

<ParamField path="onWarnings" type="(warnings: VizDiagnostic[]) => void">
  Fires with any warnings a successful compile produced.
</ParamField>

<ParamField path="onSpecChange" type="(next: Spec) => void">
  Fires with the new spec whenever a command mutates it — persist the result
  here. See [Commands & history](/sdk-next/advanced/commands-and-history).
</ParamField>

<ParamField path="handleRef" type="Ref<GraphHandle>">
  Filled with this graph's handle, for callers mounted outside the provider
  where the hooks can't reach. The handle carries `commands`, `undo`, `redo`,
  `subscribe`, `getScene`, `getSelection`, `setSelection` and
  `subscribeSelection`. See [Commands &
  history](/sdk-next/advanced/commands-and-history).
</ParamField>

<ParamField path="plugins" type="readonly Plugin[]">
  Custom geoms, stats and transforms — and their render halves — registered for
  this graph. The compiler and the render resolver are built from the same
  array, so what can render cannot diverge from what can compile. Frozen at
  mount: change the registered set by remounting with a new React `key`.
</ParamField>

## GraphRenderer

Paints the provider's scene. It must be a descendant of a `<GraphProvider>`.

<ParamField path="sizing" type="GraphSizing" default="{ mode: 'responsive' }">
  How the chart claims space. See [Sizing](/sdk-next/rendering/sizing).
</ParamField>

<ParamField path="mode" type="GraphMode" default="readonly">
  `'readonly'`, `'editable'` or `'point-and-edit'`. `'editable'` mounts whatever
  fills the `EditorSurface` slot over the chart frame; on a plain
  `GraphRenderer` that slot is empty, so no editor surface renders.
  `'point-and-edit'` mounts the same surface and makes the chart itself
  pressable: a press selects the observations under it, the band around them, or
  the chart. Use `EditableGraphRenderer` from `@graphysdk/react/editable` for an
  editing UI.
</ParamField>

<ParamField path="showTooltips" type="boolean" default="true">
  Whether hover tooltips are shown. See
  [Interactivity](/sdk-next/rendering/interactivity).
</ParamField>

<ParamField path="animation" type="GraphAnimation" default="true">
  `boolean | GraphAnimationProps`. `false` disables every animation; an object
  tunes the intro entrance (`intro`) and data transitions (`transitions`)
  separately. See [Interactivity](/sdk-next/rendering/interactivity#animation).
</ParamField>

<ParamField path="slots" type="GraphSlots">
  Per-region component overrides. `Legend`, `Headline`, `AxisTicks` and
  `AxisLabel` take a `SlotOverride` — a `{ render, measure }` pair with a stable
  `measure` reference — rather than a bare component. See
  [Slots](/sdk-next/extending/slots).
</ParamField>

<ParamField path="onResize" type="ResizeObserverOnResize">
  Called when the container resizes, in every sizing mode. Reports the graph
  container, not the panel. A geom renderer that needs the data rectangle reads
  `panelRect` from its `render` input.
</ParamField>

## Keep inputs stable

The provider recompiles when `spec` or `data` change **by reference**. If you build the spec or data inline in a component, memoize them so an unrelated re-render doesn't trigger a needless recompile:

```tsx theme={null}
function Chart({ rows }) {
  const spec = useMemo(
    () =>
      pipe(
        createSpec({ x: 'month', y: 'revenue' }),
        geom.line(),
        scale.x(),
        scale.y()
      ),
    []
  );
  const data = useMemo(() => ({ columns, rows }), [rows]);

  return (
    <GraphProvider spec={spec} data={data}>
      <GraphRenderer />
    </GraphProvider>
  );
}
```

A new `spec` costs more than the recompile: it is a new baseline, so it also [clears the undo history](/sdk-next/advanced/commands-and-history#history-lifecycle). Watch the memo's dependencies as well as the memo itself — a spec knob the host drives from its own state, like a palette dropdown or a highlight-style toggle, produces a new `spec` every time it moves and drops the user's undo stack with it. Drive knobs you want undoable through [commands](/sdk-next/advanced/commands-and-history) instead.

## Errors never blank the page

A compile failure or a render-time throw is caught and shown as an error panel in place of the chart, so a bad spec degrades gracefully instead of taking down the surrounding UI. Use `onError` to log or surface the diagnostics yourself.

## Related

* [How a chart is built](/sdk-next/concepts/how-a-chart-is-built) — the compile → render model
* [Commands & history](/sdk-next/advanced/commands-and-history) — editing the spec in place, with undo/redo
* [Sizing](/sdk-next/rendering/sizing) · [Theming](/sdk-next/rendering/theming) · [Styling](/sdk-next/config/styling) · [Slots](/sdk-next/extending/slots)


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