<Paper />

The interactive diagram canvas.

Renders the graph's elements and links, hosts user interactions (selection, drag, link creation, zoom/pan), and lets you customize each cell with your own React components. Mount inside a <GraphProvider> and size it with CSS. The canvas fills its parent.

Example

import { GraphProvider, Paper, HTMLBox, type CellRecord } from '@joint/react';

interface NodeData {
  label: string;
}

const initialCells: ReadonlyArray<CellRecord<NodeData>> = [
  { id: '1', type: 'element', position: { x: 40, y: 40 }, data: { label: 'Hello' } },
  { id: '2', type: 'element', position: { x: 280, y: 180 }, data: { label: 'World' } },
  { id: 'edge', type: 'link', source: { id: '1' }, target: { id: '2' } },
];

function Diagram() {
  return (
    <GraphProvider initialCells={initialCells}>
      <Paper
        style={{ width: '100%', height: 600 }}
        renderElement={(data: NodeData) => <HTMLBox>{data.label}</HTMLBox>}
      />
    </GraphProvider>
  );
}

See

PaperProps for the full prop surface.

Props

anchorNamespace?

readonly optional anchorNamespace?: any;

Namespace used to resolve element anchor names.

Default

JointJS built-in anchors

background?

readonly optional background?: BackgroundOptions;

Paper background color, image, or pattern. Pass an object such as { color: 'lightblue', image: '/bg.png', repeat: 'flip-xy' }.

Default

false

cellViewNamespace?

readonly optional cellViewNamespace?: any;

Namespace of cell-view constructors used to resolve a cell's view by type.

Default

JointJS built-in cell views

cellVisibility?

readonly optional cellVisibility?: CellVisibility;

Predicate deciding whether a cell should be rendered. Receives { model, isMounted, paper, graph }; return false to hide the cell. Native positional form is reachable via the options escape hatch.

className?

readonly optional className?: string;

CSS classes applied to the paper host element. Combine with width / height rules to size the paper.

---

clickThreshold?

readonly optional clickThreshold?: number;

Maximum pointer travel (in px) still treated as a click rather than a drag. Moving farther than this between press and release suppresses the pointerclick event.

Default

5

connectionPointNamespace?

readonly optional connectionPointNamespace?: any;

Namespace used to resolve connection point names.

Default

JointJS built-in connectionPoints

connectionStrategy?

readonly optional connectionStrategy?: 
  | ConnectionStrategyOptions
  | ConnectionStrategy;

Decides how the end JSON is stored when the user drops a link end.

• Function: receives { end, model, magnet, dropPoint, endType, link, paper, graph } and returns the modified EndJSON.
• Object: ConnectionStrategyOptions with pin preset and/or customize callback.

connectorNamespace?

readonly optional connectorNamespace?: any;

Namespace used to resolve connector names referenced by links.

Default

JointJS built-in connectors

defaultLink?

readonly optional defaultLink?: DefaultLink;

Defines the link created when the user starts dragging from a port or element.

Can be a factory function receiving connection context, a static LinkRecord, or a dia.Link instance.

drawGrid?

readonly optional drawGrid?: boolean | GridOptions | GridOptions[];

Draws a grid pattern on the paper background. Pass true for the default grid or an object to style it (e.g. { color: 'red', thickness: 2 }).

Default

true

drawGridSize?

readonly optional drawGridSize?: number | null;

Spacing of the rendered grid lines in px. Falls back to gridSize when not set.

Default

matches gridSize

embeddingMode?

readonly optional embeddingMode?: boolean;

Enables embedding: dropping an element onto another re-parents it (the child then moves with its parent). Pair with the validateEmbedding prop to control which parents are allowed.

Default

false

frontParentOnly?

readonly optional frontParentOnly?: boolean;

When embedding, only the frontmost element under the pointer is considered a parent; otherwise candidates are tested front-to-back.

Default

true

gridSize?

readonly optional gridSize?: number;

Grid step in px that element positions snap to while dragging.

Default

10

highlighterNamespace?

readonly optional highlighterNamespace?: any;

Namespace used to resolve highlighter names referenced by highlighting.

Default

JointJS built-in highlighters plus joint-react's magnet highlighter

highlighting?

readonly optional highlighting?: boolean | Record<string, boolean | HighlighterJSON>;

Highlighter definitions keyed by highlight type (connecting, embedding, magnet/element availability). Override to restyle these visual cues.

Default

joint-react's themed highlighters

id?

readonly optional id?: string;

Unique identifier used by joint-react to track the paper instance.

interactive?

readonly optional interactive?: CellInteractivity;

Which pointer interactions are enabled on cells. Accepts a boolean to toggle everything, an InteractivityOptions object for granular control per interaction kind, or a CellInteractivity callback returning either form per cell. The native (cellView, event) callback is reachable via the options escape hatch.

Default

{ labelMove: false, linkMove: false }

labelsLayer?

readonly optional labelsLayer?: string | boolean;

Renders link labels into a dedicated top layer (so they are not occluded by later cells). Pass true, or a layer name to target a specific layer.

Default

false

layerViewNamespace?

readonly optional layerViewNamespace?: any;

Namespace of layer-view constructors used to resolve custom paper layers.

Default

JointJS built-in layer views

linkAnchorNamespace?

readonly optional linkAnchorNamespace?: any;

Namespace used to resolve link anchor names.

Default

JointJS built-in linkAnchors

linkPinning?

readonly optional linkPinning?: boolean;

Allows dropping a link end on blank paper, pinning it to a fixed point instead of requiring an element/port.

Default

false

linkRouting?

readonly optional linkRouting?: LinkRouting;

Bundle of link routing defaults (router, connector, anchor, connection point). Use a preset (linkRoutingStraight, linkRoutingOrthogonal, linkRoutingSmooth) or pass a custom object of the same shape.

defaultLinkAnchor is reachable via the options escape hatch.

Values inside options override matching keys here.

Example

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

<Paper linkRouting={linkRoutingOrthogonal()} />

magnetThreshold?

readonly optional magnetThreshold?: string | number;

Pointer travel (in px) before a link is created from a magnet, or 'onleave' to create it once the pointer leaves the magnet.

Default

'onleave'

markAvailable?

readonly optional markAvailable?: boolean;

Highlights valid drop targets (magnets and elements) while a link is being dragged.

Default

true

moveThreshold?

readonly optional moveThreshold?: number;

Pointer travel (in px) required before pointermove events start firing.

Default

0

onBlankContextMenu?

readonly optional onBlankContextMenu?: (params) => void;

Parameters

Parameter	Type
params	PointerBlankEventParams

Returns

void

onBlankMouseEnter?

readonly optional onBlankMouseEnter?: (params) => void;

Parameters

Parameter	Type
params	HoverBlankEventParams

Returns

void

onBlankMouseLeave?

readonly optional onBlankMouseLeave?: (params) => void;

Parameters

Parameter	Type
params	HoverBlankEventParams

Returns

void

onBlankMouseOut?

readonly optional onBlankMouseOut?: (params) => void;

Parameters

Parameter	Type
params	HoverBlankEventParams

Returns

void

onBlankMouseOver?

readonly optional onBlankMouseOver?: (params) => void;

Parameters

Parameter	Type
params	HoverBlankEventParams

Returns

void

onBlankMouseWheel?

readonly optional onBlankMouseWheel?: (params) => void;

Parameters

Parameter	Type
params	WheelBlankEventParams

Returns

void

onBlankPointerClick?

readonly optional onBlankPointerClick?: (params) => void;

Parameters

Parameter	Type
params	PointerBlankEventParams

Returns

void

onBlankPointerDblClick?

readonly optional onBlankPointerDblClick?: (params) => void;

Parameters

Parameter	Type
params	PointerBlankEventParams

Returns

void

onBlankPointerDown?

readonly optional onBlankPointerDown?: (params) => void;

Parameters

Parameter	Type
params	PointerBlankEventParams

Returns

void

onBlankPointerMove?

readonly optional onBlankPointerMove?: (params) => void;

Parameters

Parameter	Type
params	PointerBlankEventParams

Returns

void

onBlankPointerUp?

readonly optional onBlankPointerUp?: (params) => void;

Parameters

Parameter	Type
params	PointerBlankEventParams

Returns

void

onCellContextMenu?

readonly optional onCellContextMenu?: (params) => void;

Parameters

Parameter	Type
params	PointerCellEventParams

Returns

void

onCellMouseEnter?

readonly optional onCellMouseEnter?: (params) => void;

Parameters

Parameter	Type
params	HoverCellEventParams

Returns

void

onCellMouseLeave?

readonly optional onCellMouseLeave?: (params) => void;

Parameters

Parameter	Type
params	HoverCellEventParams

Returns

void

onCellMouseOut?

readonly optional onCellMouseOut?: (params) => void;

Parameters

Parameter	Type
params	HoverCellEventParams

Returns

void

onCellMouseOver?

readonly optional onCellMouseOver?: (params) => void;

Parameters

Parameter	Type
params	HoverCellEventParams

Returns

void

onCellMouseWheel?

readonly optional onCellMouseWheel?: (params) => void;

Parameters

Parameter	Type
params	WheelCellEventParams

Returns

void

onCellPointerClick?

readonly optional onCellPointerClick?: (params) => void;

Parameters

Parameter	Type
params	PointerCellEventParams

Returns

void

onCellPointerDblClick?

readonly optional onCellPointerDblClick?: (params) => void;

Parameters

Parameter	Type
params	PointerCellEventParams

Returns

void

onCellPointerDown?

readonly optional onCellPointerDown?: (params) => void;

Parameters

Parameter	Type
params	PointerCellEventParams

Returns

void

onCellPointerMove?

readonly optional onCellPointerMove?: (params) => void;

Parameters

Parameter	Type
params	PointerCellEventParams

Returns

void

onCellPointerUp?

readonly optional onCellPointerUp?: (params) => void;

Parameters

Parameter	Type
params	PointerCellEventParams

Returns

void

onElementContextMenu?

readonly optional onElementContextMenu?: (params) => void;

Parameters

Parameter	Type
params	PointerElementEventParams

Returns

void

onElementMagnetContextMenu?

readonly optional onElementMagnetContextMenu?: (params) => void;

Parameters

Parameter	Type
params	MagnetEventParams

Returns

void

onElementMagnetPointerClick?

readonly optional onElementMagnetPointerClick?: (params) => void;

Parameters

Parameter	Type
params	MagnetEventParams

Returns

void

onElementMagnetPointerDblClick?

readonly optional onElementMagnetPointerDblClick?: (params) => void;

Parameters

Parameter	Type
params	MagnetEventParams

Returns

void

onElementMouseEnter?

readonly optional onElementMouseEnter?: (params) => void;

Parameters

Parameter	Type
params	HoverElementEventParams

Returns

void

onElementMouseLeave?

readonly optional onElementMouseLeave?: (params) => void;

Parameters

Parameter	Type
params	HoverElementEventParams

Returns

void

onElementMouseOut?

readonly optional onElementMouseOut?: (params) => void;

Parameters

Parameter	Type
params	HoverElementEventParams

Returns

void

onElementMouseOver?

readonly optional onElementMouseOver?: (params) => void;

Parameters

Parameter	Type
params	HoverElementEventParams

Returns

void

onElementMouseWheel?

readonly optional onElementMouseWheel?: (params) => void;

Parameters

Parameter	Type
params	WheelElementEventParams

Returns

void

onElementPointerClick?

readonly optional onElementPointerClick?: (params) => void;

Parameters

Parameter	Type
params	PointerElementEventParams

Returns

void

onElementPointerDblClick?

readonly optional onElementPointerDblClick?: (params) => void;

Parameters

Parameter	Type
params	PointerElementEventParams

Returns

void

onElementPointerDown?

readonly optional onElementPointerDown?: (params) => void;

Parameters

Parameter	Type
params	PointerElementEventParams

Returns

void

onElementPointerMove?

readonly optional onElementPointerMove?: (params) => void;

Parameters

Parameter	Type
params	PointerElementEventParams

Returns

void

onElementPointerUp?

readonly optional onElementPointerUp?: (params) => void;

Parameters

Parameter	Type
params	PointerElementEventParams

Returns

void

onLinkConnect?

readonly optional onLinkConnect?: (params) => void;

Parameters

Parameter	Type
params	LinkConnectEventParams

Returns

void

onLinkContextMenu?

readonly optional onLinkContextMenu?: (params) => void;

Parameters

Parameter	Type
params	PointerLinkEventParams

Returns

void

onLinkDisconnect?

readonly optional onLinkDisconnect?: (params) => void;

Parameters

Parameter	Type
params	LinkConnectEventParams

Returns

void

onLinkMouseEnter?

readonly optional onLinkMouseEnter?: (params) => void;

Parameters

Parameter	Type
params	HoverLinkEventParams

Returns

void

onLinkMouseLeave?

readonly optional onLinkMouseLeave?: (params) => void;

Parameters

Parameter	Type
params	HoverLinkEventParams

Returns

void

onLinkMouseOut?

readonly optional onLinkMouseOut?: (params) => void;

Parameters

Parameter	Type
params	HoverLinkEventParams

Returns

void

onLinkMouseOver?

readonly optional onLinkMouseOver?: (params) => void;

Parameters

Parameter	Type
params	HoverLinkEventParams

Returns

void

onLinkMouseWheel?

readonly optional onLinkMouseWheel?: (params) => void;

Parameters

Parameter	Type
params	WheelLinkEventParams

Returns

void

onLinkPointerClick?

readonly optional onLinkPointerClick?: (params) => void;

Parameters

Parameter	Type
params	PointerLinkEventParams

Returns

void

onLinkPointerDblClick?

readonly optional onLinkPointerDblClick?: (params) => void;

Parameters

Parameter	Type
params	PointerLinkEventParams

Returns

void

onLinkPointerDown?

readonly optional onLinkPointerDown?: (params) => void;

Parameters

Parameter	Type
params	PointerLinkEventParams

Returns

void

onLinkPointerMove?

readonly optional onLinkPointerMove?: (params) => void;

Parameters

Parameter	Type
params	PointerLinkEventParams

Returns

void

onLinkPointerUp?

readonly optional onLinkPointerUp?: (params) => void;

Parameters

Parameter	Type
params	PointerLinkEventParams

Returns

void

onLinkSnapConnect?

readonly optional onLinkSnapConnect?: (params) => void;

Parameters

Parameter	Type
params	LinkConnectEventParams

Returns

void

onLinkSnapDisconnect?

readonly optional onLinkSnapDisconnect?: (params) => void;

Parameters

Parameter	Type
params	LinkConnectEventParams

Returns

void

onPaperMouseEnter?

readonly optional onPaperMouseEnter?: (params) => void;

Parameters

Parameter	Type
params	PaperHoverEventParams

Returns

void

onPaperMouseLeave?

readonly optional onPaperMouseLeave?: (params) => void;

Parameters

Parameter	Type
params	PaperHoverEventParams

Returns

void

onPaperPan?

readonly optional onPaperPan?: (params) => void;

Parameters

Parameter	Type
params	PaperPanEventParams

Returns

void

onPaperPinch?

readonly optional onPaperPinch?: (params) => void;

Parameters

Parameter	Type
params	PaperPinchEventParams

Returns

void

onResize?

readonly optional onResize?: (params) => void;

Parameters

Parameter	Type
params	ResizeEventParams

Returns

void

onScale?

readonly optional onScale?: (params) => void;

Parameters

Parameter	Type
params	ScaleEventParams

Returns

void

onTransform?

readonly optional onTransform?: (params) => void;

Parameters

Parameter	Type
params	TransformEventParams

Returns

void

onTranslate?

readonly optional onTranslate?: (params) => void;

Parameters

Parameter	Type
params	TranslateEventParams

Returns

void

options?

readonly optional options?: PaperOptions;

Raw dia.Paper.Options passthrough for anything joint-react doesn't expose as a dedicated prop (e.g. allowLink, validateMagnet, restrictTranslate, onViewPostponed).

Values set here override top-level props of the same name, treat this as the authoritative form for users who need direct access to the raw JointJS API. Avoid overriding joint-react-controlled options (async, sorting, viewManagement, frozen, autoFreeze), the portal rendering depends on their set values.

overflow?

readonly optional overflow?: boolean;

Lets cell content spill outside the paper viewport instead of being clipped.

Default

false

paper?

readonly optional paper?: PaperView;

Pre-created paper instance to adopt. When provided, the Paper component wraps this paper instead of creating a new one. The paper's DOM is assumed to be managed externally (e.g. by a stencil).

PaperView is an internally-managed instance, not a public, importable type; you normally receive it from another joint-react construct (such as a stencil) rather than constructing it yourself.

---

portalSelector?

readonly optional portalSelector?: PortalSelector;

Paper-level override for the React portal target selector.

By default, each cell uses its own portalSelector field. ElementModel renders into its '__portal__' group, LinkModel into its root <g>. Built-in JointJS shapes have no portalSelector field and are skipped. Set this prop to force a single selector or a dynamic one across all cells.

A function receives { model, paper, graph } and may return:

• a selector string, look up that node,
• an Element, use that DOM node directly,
• null, skip rendering for this cell,
• undefined (or no return), fall back to the cell's own portalSelector.

Examples

// Render into the 'root' selector of all cells
<Paper portalSelector="root" renderElement={...} />

// Route built-in shapes to 'root'; let ElementModel cells use their default
<Paper portalSelector={({ model }) => {
  if (model.get('type') === 'standard.Rectangle') return 'root';
  // implicit: use the cell's own portalSelector
}} renderElement={...} />

---

preventContextMenu?

readonly optional preventContextMenu?: boolean;

Suppresses the browser context menu over the paper so contextmenu events can drive your own UI.

Default

true

preventDefaultBlankAction?

readonly optional preventDefaultBlankAction?: boolean;

Prevents the browser default action on blank-area pointer events.

Default

false

preventDefaultViewAction?

readonly optional preventDefaultViewAction?: boolean;

Prevents the browser default action on cell pointer events.

Default

true

renderElement?

readonly optional renderElement?: RenderElement<any>;

Renders each element from its data slice.

Note: JointJS works with SVG by default, so renderElement is appended inside an SVG node. To render HTML elements, use the experimental useHTMLOverlay prop or an SVG foreignObject.

Receives the element's data slice only. Derive its type from your cells with InferElement<typeof cells>['data'].

Examples

Global component

type NodeData = InferElement<typeof initialCells>['data']
// HTML content lives inside <HTMLBox> so it renders correctly in SVG mode.
function RenderElement(data: NodeData) {
  return <HTMLBox className="node">{data.label}</HTMLBox>
}

Local component

type NodeData = InferElement<typeof initialCells>['data']
const renderElement: RenderElement<NodeData> = useCallback(
    (data) => <HTMLBox className="node">{data.label}</HTMLBox>,
    []
)

---

renderLink?

readonly optional renderLink?: RenderLink<any>;

Experimental

This API is experimental — it may change or be removed in a future release.

Renders each link's content from its data slice. Re-runs when the link's data changes.

Note: JointJS works with SVG by default, so renderLink content is appended inside an SVG node. To render HTML elements, use an SVG foreignObject.

Receives the link's data slice only. Derive its type from your cells with InferLink<typeof cells>['data']. When you need the source, target, or id, read them with useCell() from inside the renderer.

• this feature is experimental and may have limitations or issues. Use at your own risk.

Examples

Global component

type LinkData = InferLink<typeof initialCells>['data']
function RenderLink(data: LinkData) {
  return <text>{data.label}</text>;
}

Local component

type LinkData = InferLink<typeof initialCells>['data']
const renderLink: RenderLink<LinkData> = useCallback(
  (data) => <text>{data.label}</text>,
  []
)

Reading the id alongside the data slice

type LinkData = InferLink<typeof initialCells>['data']
function RenderLink(data: LinkData) {
  // source / target / id live on the context, not the data slice
  const id = useCellId();
  return <text>{data.label} ({id})</text>;
}

---

routerNamespace?

readonly optional routerNamespace?: any;

Namespace used to resolve router names referenced by links.

Default

JointJS built-in routers

snapLabels?

readonly optional snapLabels?: boolean;

Snaps a dragged link label to the closest point on the link path.

Default

false

snapLinks?

readonly optional snapLinks?: boolean | SnapLinksOptions;

Snaps a dragged link end to nearby ports/elements. Pass { radius } to set the snapping distance in px.

Default

{ radius: 15 }

snapLinksSelf?

readonly optional snapLinksSelf?: 
  | boolean
  | {
  distance: number;
};

Allows a link end to snap to its own source/target element.

Default

false

style?

readonly optional style?: CSSProperties;

Inline styles applied to the paper host element. Use style.width and style.height (or CSS via className) to size the paper, Paper does not expose dedicated width/height props.

---

transform?

readonly optional transform?: PaperTransform;

Sets the paper's viewport transform via paper.matrix(...). Accepts either a CSS transform string (e.g. 'scale(0.5)', 'translate(10px, 20px) rotate(15deg)') or a DOMMatrix. Useful for zoom, minimap, and arbitrary viewport transforms.

Example

<Paper transform="scale(0.4)" />
<Paper transform={new DOMMatrix().scale(2).translate(10, 20)} />

---

useHTMLOverlay?

readonly optional useHTMLOverlay?: boolean;

Experimental

This API is experimental — it may change or be removed in a future release.

Renders elements as real HTML in an overlay instead of inside an SVG node. By default renderElement output is mounted in SVG, so plain HTML needs a foreignObject (or an HTMLBox); enable this to skip that wrapping. Known issues with HTML element rendering — use at your own risk.

Default

false

---

validateConnection?

readonly optional validateConnection?: 
  | CanConnectOptions
  | ValidateConnection;

Validates whether a connection between two elements/ports is allowed.

• Function: custom validation with built-in rules (no self-loops, no link-to-link, no multi-links). Receives { source, target, endType, paper, graph }.
• Object: CanConnectOptions with built-in rules and optional validate callback.

When omitted, defaults to canConnect() (no self-loops, no link-to-link, no multi-links).

validateEmbedding?

readonly optional validateEmbedding?: ValidateEmbedding;

Validates whether an element can be embedded into another element. Receives { child, parent, paper, graph }.

validateUnembedding?

readonly optional validateUnembedding?: ValidateUnembedding;

Validates whether an element can be unembedded from its parent. Receives { child, paper, graph }.