useOnPaperEvents()

On the current paper

function useOnPaperEvents(handlers): void;

Subscribes to dia.Paper events, pointer clicks, hovers, drags, link connections, zoom/pan, and more, so you can respond to user interaction on the canvas. When no paper argument is given, the hook targets the paper from the surrounding Paper context (or the single default paper). Mount it inside a <GraphProvider>. Unlike useOnGraphEvents, it tolerates a paper that has not mounted yet — it does not throw while waiting and subscribes once a paper becomes available.

Two key forms can be mixed in the same handlers map:

CamelCase form: on<Category><Event> keys deliver a single params object with named properties.

useOnPaperEvents({
  onElementPointerClick: ({ id, model, paper, graph, event, x, y }) => {},
  onBlankPointerClick: ({ paper, graph, event, x, y }) => {},
});

Raw form: native JointJS event names with positional arguments. Use for events without an on* counterpart ('render:done', 'cell:highlight', …).

useOnPaperEvents(paperId, {
  'element:pointerclick': (view, evt, x, y) => {},
  'render:done': (stats) => {},
});

Handlers are always-latest: the subscription is established once and each event reads the current handler, so inline maps and closures need no useCallback. Re-subscription happens only when the paper or the set of event names changes.

The on* params object omits the React-store record, to read the record shape, call useCell(id, selector) from your own component (the handler closure has access to the id it emits).

See PaperEventMap for every accepted key, and PaperEventHandler for typing an individual handler.

Parameters

Parameter	Type	Description
handlers	PaperEventMap	Map of paper events to callbacks (camelCase on* and/or raw).

Returns

void

Example

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

function SelectionLogger() {
  useOnPaperEvents({
    onElementPointerClick: ({ id }) => console.log('clicked element', id),
    onBlankPointerClick: ({ x, y }) => console.log('clicked blank at', x, y),
  });
  return null;
}

<GraphProvider>
  <Paper renderElement={() => <rect width={80} height={40} fill="#3498db" />} />
  <SelectionLogger />
</GraphProvider>

On a specific paper

function useOnPaperEvents(paperTarget, handlers): void;

Subscribes to paper events on a specific paper you name, by registered id, dia.Paper instance, or React ref. Use this to target one paper when several are mounted (e.g. a main canvas plus a minimap). Same camelCase/raw handler forms and always-latest semantics as the context form.

Parameters

Parameter	Type	Description
paperTarget	PaperTarget	The paper to listen on, see PaperTarget.
handlers	PaperEventMap	Map of paper events to callbacks (camelCase on* and/or raw).

Returns

void

Example

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

// Target a paper by its registered id.
function MinimapLogger() {
  useOnPaperEvents('minimap', {
    onBlankPointerClick: ({ x, y }) => console.log('minimap click', x, y),
  });
  return null;
}