<GraphProvider />

Creates (or adopts) a JointJS graph and shares it with every <Paper> and graph hook rendered inside it. Mount it near the root of your diagram: hooks like useGraph, useCells, and useCell read the graph from its context and throw when used outside a provider.

It works in three modes, depending on which props you pass: pass initialCells to let JointJS own the graph after mount (uncontrolled), pass cells + onCellsChange to drive the graph from React state (controlled), or pass onIncrementalCellsChange to forward deltas to an external store.

Type Parameters

Type Parameter	Default type
Element extends ElementJSONInit	ElementJSONInit
Link extends LinkJSONInit	LinkJSONInit

Examples

Uncontrolled — seed once, JointJS owns the graph

import { GraphProvider, Paper } from '@joint/react';

// `renderElement` receives the element's `data` slice only — not its
// geometry. Read position/size with the context hooks (e.g. useCell) when
// you need them.
<GraphProvider
  initialCells={[{ id: '1', type: 'element', position: { x: 20, y: 20 }, size: { width: 80, height: 40 }, data: { label: 'A' } }]}
>
  <Paper renderElement={(data) => <rect width={80} height={40} rx={4} fill="#4763ff" />} />
</GraphProvider>

Controlled — React state owns the cells

import { useState } from 'react';
import { GraphProvider, Paper, type CellRecord } from '@joint/react';

const [cells, setCells] = useState<readonly CellRecord[]>([]);
<GraphProvider cells={cells} onCellsChange={setCells}>
  <Paper />
</GraphProvider>

Incremental — forward deltas to an external store

import { GraphProvider, Paper } from '@joint/react';

<GraphProvider
  onIncrementalCellsChange={(delta) => {
    // forward the { added, changed, removed } delta to your external store
    store.apply(delta);
  }}
>
  <Paper />
</GraphProvider>

See

GraphProviderProps for the full list of props.

Props

autoSizeOrigin?

readonly optional autoSizeOrigin?: AutoSizeOrigin;

Reference point that stays fixed when an auto-sized element's measured size changes (via useMeasureElement). Mirrors CSS transform-origin semantics.

• 'top-left' (default): element grows right/down.
• 'center': element grows symmetrically, its geometric center stays put.

Only affects measurement-driven writes. Manual cell.resize(), interactive resize tools, and direct cell.set('size', ...) calls are unaffected.

Default

'top-left'

---

cellModel?

readonly optional cellModel?: typeof Cell;

Base model class used for every cell the graph constructs from JSON. Maps to the (deprecated) cellModel option of dia.Graph; prefer cellNamespace, which registers shapes by type and supports per-type model classes.

See

dia.Graph

---

cellNamespace?

readonly optional cellNamespace?: unknown;

Cell namespace passed to new dia.Graph. Your entries are merged on top of the built-ins, so JointJS shapes and the @joint/react ElementModel / LinkModel stay available even when you register custom shapes.

Default

JointJS shapes plus the @joint/react cell models

---

cells?

readonly optional cells?: ProviderCells<Element, Link>;

Controlled cells array. Whenever this array changes, the graph is re-synced to match it (and initialCells is ignored); passing the same reference on a re-render does not re-sync. Pair it with onCellsChange to mirror user edits back into your own state.

---

children?

readonly optional children?: ReactNode;

React children rendered inside the provider, typically a <Paper />.

---

graph?

readonly optional graph?: Graph<Attributes, ModelSetOptions>;

Pre-existing JointJS graph instance to use. If omitted, GraphProvider creates a fresh new dia.Graph(...).

See

dia.Graph

---

initialCells?

readonly optional initialCells?: readonly CellInput<Element, Link>[];

Cells used to seed the graph once, at mount, for uncontrolled mode. Later changes to this array are not applied. Ignored when cells is provided.

See

CellInput

---

onCellsChange?

readonly optional onCellsChange?: (newCells) => void;

Fires after each graph change with the full, updated cells array. Use it to keep external React state in sync with the graph; it is notification only and does not itself write anything back into the graph.

Parameters

Parameter	Type
newCells	ProviderCells<Element, Link>

Returns

void

---

onIncrementalCellsChange?

readonly optional onIncrementalCellsChange?: OnIncrementalCellsChange<Element, Link>;

Fires after each commit with the granular added / changed / removed delta, so you can apply just the change to an external store (Redux, Zustand, etc.). Works in both controlled and uncontrolled mode.

See

IncrementalCellsChange