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 spec={spec} data={data} colorScheme="light">
  <GraphRenderer sizing={{ mode: 'responsive' }} />
</GraphProvider>;

GraphProvider

Holds the inputs and produces the scene. It recompiles when spec, data or colorScheme change by reference. A data or scheme change keeps layer ids; a spec change is a full compile. The provider from @graphysdk/react turns the “Made with Graphy” brand mark on unless the spec says otherwise. config({ content: { brandMark: { enabled: false } } }) turns it off. See Content.

Data

required

The data table the spec draws from.

Spec

required

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

ColorScheme

default:"light"

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

Theme

A theme: a stylesheet, palettes, config defaults and geom repaints that sit beneath the spec’s own. Read once at mount; change the React key to switch themes. A theme that names a colorScheme overrides the colorScheme prop.

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 shows an error panel in place rather than going blank.

(warnings: VizDiagnostic[]) => void

Fires with any warnings a successful compile produced.

(next: Spec) => void

Fires with the new spec whenever a command changes 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 cannot reach. The handle carries commands, undo, redo, subscribe, getScene, getSelection, setSelection and subscribeSelection. See Commands & history.

readonly Plugin[]

Custom geoms, stats and transforms, with their render halves, registered for this graph. The compiler and the render resolver are built from the same array, so what can render cannot differ from what can compile. Frozen at mount: change the set by remounting with a new React key.

boolean

default:"true"

A published production browser build sends one anonymous count the first time this provider has a scene. Set this to false to turn that off.

GraphRenderer

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

GraphSizing

default:"{ mode: 'responsive' }"

How the chart claims space. See Sizing.

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. Neither editing mode shows a tooltip, and 'point-and-edit' draws no annotations and no hover paint. Use EditableGraphRenderer from @graphysdk/react/editable for an editing UI.

boolean

default:"true"

false hides the tooltip whatever config.tooltip.mode says; true lets the spec decide. See Interactivity.

GraphAnimation

default:"true"

boolean | GraphAnimationProps. false disables every animation. An object tunes the intro entrance (intro), data transitions (transitions) and the geom count above which nothing animates (maxAnimatedGeoms). A reduced-motion preference disables everything. 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.

EditableGraphRenderer takes the same props, plus what only the editor reads:

PalettePresets

Named color lists, Record<string, readonly string[]>, that the Chart menu’s Palette row offers in point and edit after the theme’s own colors. Picking one writes its colors as the color scale’s range, so the spec keeps them whatever the host offers later, and a chart with no groups takes its first color. Without any, the row is hidden.

EditMenus

A host’s edit menus, searched before Graphy’s in point and edit. null removes that menu. A missing entry leaves Graphy’s in place.

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 does not recompile for nothing:

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 once it compiles it also clears the undo history. Watch the memo’s dependencies as well as the memo itself: a spec setting 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 settings 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 does not take 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

Themes

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