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.

import { GraphProvider, GraphRenderer } from '@graphysdk/react';

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

GraphProvider

Holds the inputs and produces the compiled spec. It recompiles when input, data, customPalettes or colorScheme change by reference (a scheme change keeps layer ids, like a data change); themeOverrides re-paints without a recompile.

Data

required

The data table the spec draws from.

SpecInput

required

The chart to compile — a spec from createSpec/pipe.

ColorScheme

default:"light"

'light' or 'dark'. Selects the base chrome token set, decides which half of every { light, dark } stylesheet color and token() pair paints, and picks the tones of the default mono palette. See Theming.

ThemeOverrides

Per-token overrides for the HTML chrome, layered over the base token set. See Theming.

CustomPalettesInput

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.

Locale

Locale for formatting displayed values. See Formatting & locale.

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

(warnings: VizDiagnostic[]) => void

Fires with any warnings a successful compile produced.

(next: SpecInput) => void

Fires with the new spec whenever a command mutates it — persist the result here. See Commands & history.

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, getCompiled, getSelection, setSelection and subscribeSelection. See Commands & history.

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.

GraphRenderer

Paints the provider’s compiled spec. It must be a descendant of a <GraphProvider>.

GraphSizing

default:"{ mode: 'responsive' }"

How the chart claims space. See Sizing.

GraphMode

default:"readonly"

'readonly' or 'editable'. 'editable' mounts whatever fills the EditorSurface slot over the chart frame; on a plain GraphRenderer that slot is empty, so no editor surface renders. Use EditableGraphRenderer from @graphysdk/react/editable for an editing UI.

boolean

default:"true"

Whether hover tooltips are shown. See Interactivity.

GraphAnimation

default:"true"

boolean | GraphAnimationProps. false disables every animation; an object tunes the intro entrance (intro) and data transitions (transitions) separately. See Interactivity.

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.

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.

Keep inputs stable

The provider recompiles when input 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:

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 input={spec} data={data}>
      <GraphRenderer />
    </GraphProvider>
  );
}

A new input costs more than the recompile: it is a new baseline, so it also clears the undo history. 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 input every time it moves and drops the user’s undo stack with it. Drive knobs you want undoable through commands 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.

How a chart is built — the compile → render model
Commands & history — editing the spec in place, with undo/redo
Sizing · Theming · Styling · Slots

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

GraphProvider

GraphRenderer

Keep inputs stable

Errors never blank the page

​GraphProvider

​GraphRenderer

​Keep inputs stable

​Errors never blank the page

​Related

GraphProvider

GraphRenderer

Keep inputs stable

Errors never blank the page

Related