useCells()

Subscribe to a collection

function useCells<Cell>(collection): readonly Computed<Cell>[];

Subscribe to a collection's cells. Tracks collection membership (add/remove/reset) and reads cell records from the GraphProvider's container. Cells not in the graph (e.g. ui.Clipboard clones) fall back to the collection's own dia.Cell instances, converted to records on demand.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form

Parameters

Parameter	Type	Description
collection	Collection<Cell<Attributes<Selectors>, ModelSetOptions>>	JointJS collection whose member IDs drive the subscription

Returns

readonly Computed<Cell>[]

readonly resolved cells array filtered by collection membership

Select from a collection

function useCells<Cell, Selected>(collection, selector, isEqual?): Selected;

Subscribe to a collection's cells with a selector.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form
Selected	readonly Computed<Cell>[]	selector return type

Parameters

Parameter	Type	Description
collection	Collection<Cell<Attributes<Selectors>, ModelSetOptions>>	JointJS collection whose member IDs drive the subscription
selector	(cells) => Selected	derive a value from the picked resolved cells array
isEqual?	(a, b) => boolean	equality test used to short-circuit re-renders (defaults to a shallow, array-aware comparison that falls back to Object.is for scalar results)

Returns

Selected

selected value

Subscribe to all cells

function useCells<Cell>(): readonly Computed<Cell>[];

Subscribe to the full cells array.

Returned array reference is stable across data-only mutations (the internal container mutates items in-place). Size changes produce a new snapshot token.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form

Returns

readonly Computed<Cell>[]

readonly resolved cells array

Example

import { useCells } from '@joint/react';

function CellCount() {
  const cells = useCells();
  return <span>{cells.length} cells</span>;
}

Subscribe to a cell by id

function useCells<Cell>(id): Computed<Cell> | undefined;

Subscribe to a single cell by id.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form

Parameters

Parameter	Type	Description
id	ID	cell id to track

Returns

Computed<Cell> | undefined

current resolved cell, or undefined when missing

Select from a cell by id

function useCells<Cell, Selected>(id, selector, isEqual?): Selected;

Subscribe to a single cell by id and derive a value from it. Subscribes only to that id so unrelated mutations don't trigger re-renders. A nullish id resolves to no cell, so the selector runs against undefined, handy for optional selection state (useCells(selectedId, ...)) with no ?? ''.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form
Selected	Computed<Cell> | undefined	selector return type (defaults to `Cell

Parameters

Parameter	Type	Description
id	ID | null | undefined	cell id to track (nullish → selector receives undefined)
selector	(cell) => Selected	derive a value from the cell (or undefined when missing)
isEqual?	(a, b) => boolean	equality test used to short-circuit re-renders (defaults to a shallow, array-aware comparison that falls back to Object.is for scalar results)

Returns

Selected

selected value

Subscribe to specific cells

function useCells<Cell>(ids): readonly Computed<Cell>[];

Subscribe to a specific set of cells by id. Subscribes only to those ids (not the full container) so unrelated mutations don't trigger re-renders. Returns the picked cells in the order they appear in ids; missing ids are skipped. The array reference is stable when no picked cell changed.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form

Parameters

Parameter	Type	Description
ids	readonly ID[]	cell ids to track

Returns

readonly Computed<Cell>[]

array of resolved cells (only those that exist; missing ids are skipped)

Select from specific cells

function useCells<Cell, Selected>(ids, selector, isEqual?): Selected;

Subscribe to a specific set of cells by id and derive a value from them. Subscribes only to those ids; the selector receives the picked cells array.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form
Selected	readonly Computed<Cell>[]	selector return type (defaults to readonly Cell[])

Parameters

Parameter	Type	Description
ids	readonly ID[]	cell ids to track
selector	(cells) => Selected	derive a value from the picked resolved cells array
isEqual?	(a, b) => boolean	equality test used to short-circuit re-renders (defaults to a shallow, array-aware comparison that falls back to Object.is for scalar results)

Returns

Selected

selected value

Subscribe via a selector

function useCells<Cell, Selected>(selector, isEqual?): Selected;

Subscribe via a selector. Runs on every commit; return equal values to skip re-render.

Type Parameters

Type Parameter	Default type	Description
Cell extends AnyCellRecord	CellRecord	input cell record shape (defaults to CellRecord); reads resolve to its Computed form
Selected	readonly Computed<Cell>[]	selector return type (defaults to readonly Cell[])

Parameters

Parameter	Type	Description
selector	(cells) => Selected	derive a value from the resolved cells array
isEqual?	(a, b) => boolean	equality test used to short-circuit re-renders (defaults to a shallow, array-aware comparison that falls back to Object.is for scalar results)

Returns

Selected

selected value

Example

import { useCells } from '@joint/react';

function ElementCount() {
  // Counts cells whose type is the default 'element' and re-renders only when
  // that count changes; shape-typed elements (e.g. 'standard.Rectangle') are
  // not included.
  const count = useCells((cells) => cells.filter((cell) => cell.type === 'element').length);
  return <span>{count} elements</span>;
}