useSelection()

function useSelection(paperTarget?): SelectionApi;

Returns an imperative handle for the nearest paper's Selection feature — read the current selection, start a region gesture, select all elements, or set the selection programmatically.

Requires a <Diagram> ancestor: the diagram owns the stable mvc.Collection<dia.Cell> exposed as handle.collection, which is always present. handle.selection stays null until a <Selection> feature mounts on the resolved paper, and startSelectionRegion is a no-op resolving to null until then.

This hook does not subscribe to reactive state, it never re-renders when the selection changes. Use useCells(handle.collection, ...) for reactive reads, or useIsCellSelected inside a cell renderer.

Parameters

Parameter	Type	Description
paperTarget?	PaperTarget	Paper to read the selection from. Accepts a string id, a RefObject<dia.Paper>, a dia.Paper instance, or undefined to use the nearest <Paper> context.

Returns

A SelectionApi.

collection

readonly collection: Collection<Cell<Attributes<Selectors>, ModelSetOptions>>;

Stable mvc collection of the selected cells, provided by <Diagram>.

---

selectAllElements

readonly selectAllElements: () => void;

Select every element in the graph (links excluded).

Returns

void

---

selectCells

readonly selectCells: SelectCells;

Programmatically replace the selection. See SelectCells.

---

selection

readonly selection: Selection<Collection<any>> | null;

The underlying ui.Selection view, or null until <Selection> mounts.

---

startSelectionRegion

readonly startSelectionRegion: (options?) => Promise<Cell<Attributes<Selectors>, ModelSetOptions>[] | null>;

Start a rubber-band region gesture and resolve to the cells it enclosed, or null if the gesture was cancelled or no <Selection> has mounted yet. Configure the gesture per call with StartSelectionRegionOptions.

Parameters

Parameter	Type
options?	StartSelectionRegionOptions

Returns

Promise<Cell<Attributes<Selectors>, ModelSetOptions>[] | null>

Example

import { useSelection } from '@joint/react-plus';

function SelectionToolbar() {
  const { selectAllElements, startSelectionRegion } = useSelection();
  return (
    <>
      <button onClick={selectAllElements}>Select all</button>
      <button onClick={() => startSelectionRegion({ type: 'polygon' })}>
        Lasso
      </button>
    </>
  );
}