useGraph()

function useGraph<Element, Link>(): GraphApi<Element, Link>;

Access the graph together with its imperative cell-mutation API for adding, updating, removing, and serializing cells. Call this inside a GraphProvider.

Type Parameters

Type Parameter	Default type	Description
Element extends ElementJSONInit	ElementJSONInit	element record shape (use ElementRecord<MyData> for input, Computed<ElementRecord<MyData>> for read shapes)
Link extends LinkJSONInit	LinkJSONInit	link record shape (use LinkRecord<MyData> / Computed<LinkRecord<MyData>>)

Returns

The GraphApi: the dia.Graph instance plus setCell, setCellData, removeCell, resetCells, exportToJSON, and the other cell actions.

exportToJSON

readonly exportToJSON: (options?) => JSON;

Serialize the graph to a plain JSON object.

By default the output is minimal: attributes that match each cell's defaults are dropped and empty {} placeholders are pruned everywhere except inside attrs at the third nesting level (e.g. attrs.text.textWrap: {} is a meaningful reset marker in JointJS shapes and must survive). Pass { includeDefaults: true } to keep every attribute on every cell, no pruning is applied in that mode.

Parameters

Parameter	Type
options?	ExportToJSONOptions

Returns

JSON

---

graph

readonly graph: Graph;

The JointJS graph instance.

---

importFromJSON

readonly importFromJSON: (json) => void;

Replace the graph contents from a previously exported JSON object (e.g. produced by exportToJSON). Triggers JointJS's reset event so all React subscriptions resync automatically.

Parameters

Parameter	Type
json	JSON

Returns

void

---

isElement

readonly isElement: (input) => input is Element;

Predicate / type guard: true when the input resolves to an element cell. Consults the graph's type registry so any dia.Element subclass (including custom shapes) is recognised, not just the default ElementModel.

Parameters

Parameter	Type
input	Element | Link

Returns

input is Element

---

isLink

readonly isLink: (input) => input is Link;

Predicate / type guard: true when the input resolves to a link cell. Consults the graph's type registry so any dia.Link subclass (including custom shapes) is recognised, not just the default LinkModel.

Parameters

Parameter	Type
input	Element | Link

Returns

input is Link

---

removeCell

readonly removeCell: (cellRef?, metadata?) => void;

Remove a cell by id or dia.Cell reference. A nullish reference warns in dev and no-ops; a reference that resolves to no cell is a silent no-op. The optional metadata is forwarded as the graph.removeCells event opt.

Parameters

Parameter	Type
cellRef?	CellRef | null
metadata?	Record<string, unknown>

Returns

void

---

removeCells

readonly removeCells: (cellRefs?, metadata?) => void;

Remove multiple cells by id or dia.Cell reference. A nullish array warns in dev and no-ops; references that resolve to no cell are silently skipped. The optional metadata is forwarded as the graph.removeCells event opt.

Parameters

Parameter	Type
cellRefs?	readonly CellRef[] | null
metadata?	Record<string, unknown>

Returns

void

---

resetCells

readonly resetCells: (input, metadata?) => void;

Atomically replace the cell set. Accepts dia.Cell instances alongside records. The optional metadata is forwarded as the graph.resetCells opt.

Parameters

Parameter	Type
input	ArrayUpdate<Element | Link, CellInput<Element, Link>>
metadata?	Record<string, unknown>

Returns

void

---

setCell

readonly setCell: SetCell<Element, Link>;

Add or update a cell. Two forms:

• setCell(record), record.id names the target. Existing cell: attributes merge over it. Missing cell: the cell is added.
• setCell(id, (prev) => next), updater form. The updater is invoked once with the real previous record. A nullish id, or an id with no matching cell, warns in dev and no-ops (use the direct form to add).

---

setCellData

readonly setCellData: SetCellData<HandleCellData<Element, Link>>;

Set a single cell's data field. Two forms, both keyed by cell id:

• setCellData(id, data), replaces the cell's data with data.
• setCellData(id, (prev) => next), updater form; prev is the current data, the return value replaces it (merge inside the updater for a partial update). A nullish id, or an id with no matching cell, warns in dev and no-ops.

The data type is derived from the useGraph<Element, Link> generics: typed records flow through, otherwise it falls back to Record<string, unknown>. A cell id can't be narrowed to element-vs-link at the type level, so when both are typed the updater sees their union. Narrow inside it, or fix the data shape via useGraph<ElementRecord<MyData>>().

---

transaction

readonly transaction: Transaction;

Run a callback as one atomic transaction: every edit inside collapses into a single undo entry and (for sync callbacks) a single re-render. Pass { rollbackOnError: true } to restore the graph on error (off by default — partial edits stay; enabling it snapshots the full cells array up-front, so leave off for large graphs when the callback is trusted). See Transaction.

---

updateCells

readonly updateCells: (updater, metadata?) => void;

Apply an updater to the current cells array. Updater may return dia.Cell instances. The optional metadata is forwarded as the sync event opt.

Parameters

Parameter	Type
updater	(previous) => readonly CellInput<Element, Link>[]
metadata?	Record<string, unknown>

Returns

void

Example

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

function Toolbar() {
  const { setCell, exportToJSON } = useGraph();
  return (
    <button
      onClick={() =>
        setCell({
          id: 'node-1',
          type: 'standard.Rectangle',
          position: { x: 40, y: 40 },
          size: { width: 120, height: 60 },
        })
      }
    >
      Add node
    </button>
  );
}

function App() {
  return (
    <GraphProvider>
      <Paper />
      <Toolbar />
    </GraphProvider>
  );
}