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

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 Graphy badge on unless the spec says otherwise. config({ content: { graphyBadge: { visible: 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.
FormattingLocale
Any BCP-47 tag for formatting displayed values, such as it-IT. 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 updated spec after a committed edit, undo or redo. Use it to save changes. See Saving the chart.
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, formattingLocale, 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"
How the chart responds to the reader.
  • 'readonly': hover, tooltip and animation, no editing.
  • 'annotate': mounts whatever fills the EditorSurface slot over the chart frame, for annotations and inline text. No tooltip.
  • 'edit': mounts the same surface and makes the chart pressable: a press selects the observations under it, the band around them, a guide, or the chart. No tooltip, annotations or hover paint.
  • 'static': draws the chart and its annotations once, with no hover, tooltip, legend popover or animation. For exports, thumbnails and print. Links still open.
On a plain GraphRenderer the EditorSurface slot is empty, so the editing modes render no editor. Use EditableGraphRenderer from @graphysdk/react/editable for an editing UI. See Editing.
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 calls useGeomPanelSize() in the component it paints with.
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 edit mode 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 edit mode. null removes that menu. A missing entry leaves Graphy’s in place. Graphy’s own menus (BarEditMenu, LineEditMenu, AxisEditMenu, GridEditMenu, LegendEditMenu) and rows (ColorRow, PaletteRow) are exported, so a host’s menu can draw them and add its own rows.

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:
A new spec recompiles the chart and clears its undo history once compilation succeeds. This includes specs rebuilt by a memo when its dependencies change. Use commands for settings the user should be able to undo, such as a palette change. Passing the exact value received from onSpecChange back as spec is an exception: it preserves history and does not recompile.

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.