Function useGraph

Returns GraphApi<Element, Link>

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

• ReadonlyexportToJSON: (options?: ExportToJSONOptions) => 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.

• Readonlygraph: Graph

  The JointJS graph instance.

• ReadonlyimportFromJSON: (json: 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.

• ReadonlyisElement: (input: Element | Link) => 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.

• ReadonlyisLink: (input: Element | Link) => 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.

• ReadonlyremoveCell: (cellRef?: CellRef | null, metadata?: Record<string, unknown>) => 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.

• ReadonlyremoveCells: (
      cellRefs?: readonly CellRef[] | null,
      metadata?: Record<string, unknown>,
  ) => 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.

• ReadonlyresetCells: (
      input: ArrayUpdate<Element | Link, CellInput<Element, Link>>,
      metadata?: Record<string, unknown>,
  ) => void

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

• ReadonlysetCell: 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).

• ReadonlysetCellData: 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>>().

• Readonlytransaction: 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.

• ReadonlyupdateCells: (
      updater: (
          previous: readonly (Element | Link)[],
      ) => readonly CellInput<Element, Link>[],
      metadata?: Record<string, unknown>,
  ) => 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.

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>
  );
}
Copy