Variable PaperConst

Type Declaration

• • (props: PaperProps & { ref?: Ref<Paper | null> }): ReactNode

  • Parameters

    • props: PaperProps & { ref?: Ref<Paper | null> }

      Props for Paper — the React-friendly surface over dia.Paper.Options, plus joint-react extras such as custom cell rendering, a controlled viewport transform, and portal targeting.

      Paper events are exposed directly as props (onBlankContextMenu, onElementPointerClick, onLinkMouseEnter, …). Each handler receives a single params object, e.g. onBlankContextMenu={({ paper, event, x, y }) => …}.

      Handlers are always-latest: the paper subscribes once and each event reads the current handler, so inline arrows (onBlankContextMenu={() => …}) are fine, no useCallback needed and no re-subscription on render. For raw native event names or events without an on* form (render:done, cell:highlight, …), use the useOnPaperEvents hook.

      • Optional ReadonlyanchorNamespace?: any

        Namespace used to resolve element anchor names.

        Default

        JointJS built-in anchors

      • Optional Readonlybackground?: BackgroundOptions

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

        Default

        false
        Copy

      • Optional ReadonlycellViewNamespace?: any

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

        Default

        JointJS built-in cell views
        Copy

      • Optional ReadonlycellVisibility?: 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.

      • Optional ReadonlyclassName?: string

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

      • Optional ReadonlyclickThreshold?: 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
        Copy

      • Optional ReadonlyconnectionPointNamespace?: any

        Namespace used to resolve connection point names.

        Default

        JointJS built-in connectionPoints

      • Optional ReadonlyconnectionStrategy?: 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.

      • Optional ReadonlyconnectorNamespace?: any

        Namespace used to resolve connector names referenced by links.

        Default

        JointJS built-in connectors

      • Optional ReadonlydefaultLink?: 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.

      • Optional ReadonlydrawGrid?: 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
        Copy

      • Optional ReadonlydrawGridSize?: number | null

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

        Default

        matches gridSize

      • Optional ReadonlyembeddingMode?: 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
        Copy

      • Optional ReadonlyfrontParentOnly?: boolean

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

        Default

        true
        Copy

      • Optional ReadonlygridSize?: number

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

        Default

        10
        Copy

      • Optional ReadonlyhighlighterNamespace?: any

        Namespace used to resolve highlighter names referenced by highlighting.

        Default

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

      • Optional Readonlyhighlighting?: 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
        Copy

      • Optional Readonlyid?: string

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

      • Optional Readonlyinteractive?: 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 }
        Copy

      • Optional ReadonlylabelsLayer?: 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
        Copy

      • Optional ReadonlylayerViewNamespace?: any

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

        Default

        JointJS built-in layer views
        Copy

      • Optional ReadonlylinkAnchorNamespace?: any

        Namespace used to resolve link anchor names.

        Default

        JointJS built-in linkAnchors

      • Optional ReadonlylinkPinning?: boolean

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

        Default

        false
        Copy

      • Optional ReadonlylinkRouting?: 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()} />
        Copy

      • Optional ReadonlymagnetThreshold?: 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'
        Copy

      • Optional ReadonlymarkAvailable?: boolean

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

        Default

        true
        Copy

      • Optional ReadonlymoveThreshold?: number

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

        Default

        0
        Copy

      • Optional ReadonlyonBlankContextMenu?: (params: PointerBlankEventParams) => void

      • Optional ReadonlyonBlankMouseEnter?: (params: HoverBlankEventParams) => void

      • Optional ReadonlyonBlankMouseLeave?: (params: HoverBlankEventParams) => void

      • Optional ReadonlyonBlankMouseOut?: (params: HoverBlankEventParams) => void

      • Optional ReadonlyonBlankMouseOver?: (params: HoverBlankEventParams) => void

      • Optional ReadonlyonBlankMouseWheel?: (params: WheelBlankEventParams) => void

      • Optional ReadonlyonBlankPointerClick?: (params: PointerBlankEventParams) => void

      • Optional ReadonlyonBlankPointerDblClick?: (params: PointerBlankEventParams) => void

      • Optional ReadonlyonBlankPointerDown?: (params: PointerBlankEventParams) => void

      • Optional ReadonlyonBlankPointerMove?: (params: PointerBlankEventParams) => void

      • Optional ReadonlyonBlankPointerUp?: (params: PointerBlankEventParams) => void

      • Optional ReadonlyonCellContextMenu?: (params: PointerCellEventParams) => void

      • Optional ReadonlyonCellMouseEnter?: (params: HoverCellEventParams) => void

      • Optional ReadonlyonCellMouseLeave?: (params: HoverCellEventParams) => void

      • Optional ReadonlyonCellMouseOut?: (params: HoverCellEventParams) => void

      • Optional ReadonlyonCellMouseOver?: (params: HoverCellEventParams) => void

      • Optional ReadonlyonCellMouseWheel?: (params: WheelCellEventParams) => void

      • Optional ReadonlyonCellPointerClick?: (params: PointerCellEventParams) => void

      • Optional ReadonlyonCellPointerDblClick?: (params: PointerCellEventParams) => void

      • Optional ReadonlyonCellPointerDown?: (params: PointerCellEventParams) => void

      • Optional ReadonlyonCellPointerMove?: (params: PointerCellEventParams) => void

      • Optional ReadonlyonCellPointerUp?: (params: PointerCellEventParams) => void

      • Optional ReadonlyonElementContextMenu?: (params: PointerElementEventParams) => void

      • Optional ReadonlyonElementMagnetContextMenu?: (params: MagnetEventParams) => void

      • Optional ReadonlyonElementMagnetPointerClick?: (params: MagnetEventParams) => void

      • Optional ReadonlyonElementMagnetPointerDblClick?: (params: MagnetEventParams) => void

      • Optional ReadonlyonElementMouseEnter?: (params: HoverElementEventParams) => void

      • Optional ReadonlyonElementMouseLeave?: (params: HoverElementEventParams) => void

      • Optional ReadonlyonElementMouseOut?: (params: HoverElementEventParams) => void

      • Optional ReadonlyonElementMouseOver?: (params: HoverElementEventParams) => void

      • Optional ReadonlyonElementMouseWheel?: (params: WheelElementEventParams) => void

      • Optional ReadonlyonElementPointerClick?: (params: PointerElementEventParams) => void

      • Optional ReadonlyonElementPointerDblClick?: (params: PointerElementEventParams) => void

      • Optional ReadonlyonElementPointerDown?: (params: PointerElementEventParams) => void

      • Optional ReadonlyonElementPointerMove?: (params: PointerElementEventParams) => void

      • Optional ReadonlyonElementPointerUp?: (params: PointerElementEventParams) => void

      • Optional ReadonlyonLinkConnect?: (params: LinkConnectEventParams) => void

      • Optional ReadonlyonLinkContextMenu?: (params: PointerLinkEventParams) => void

      • Optional ReadonlyonLinkDisconnect?: (params: LinkConnectEventParams) => void

      • Optional ReadonlyonLinkMouseEnter?: (params: HoverLinkEventParams) => void

      • Optional ReadonlyonLinkMouseLeave?: (params: HoverLinkEventParams) => void

      • Optional ReadonlyonLinkMouseOut?: (params: HoverLinkEventParams) => void

      • Optional ReadonlyonLinkMouseOver?: (params: HoverLinkEventParams) => void

      • Optional ReadonlyonLinkMouseWheel?: (params: WheelLinkEventParams) => void

      • Optional ReadonlyonLinkPointerClick?: (params: PointerLinkEventParams) => void

      • Optional ReadonlyonLinkPointerDblClick?: (params: PointerLinkEventParams) => void

      • Optional ReadonlyonLinkPointerDown?: (params: PointerLinkEventParams) => void

      • Optional ReadonlyonLinkPointerMove?: (params: PointerLinkEventParams) => void

      • Optional ReadonlyonLinkPointerUp?: (params: PointerLinkEventParams) => void

      • Optional ReadonlyonLinkSnapConnect?: (params: LinkConnectEventParams) => void

      • Optional ReadonlyonLinkSnapDisconnect?: (params: LinkConnectEventParams) => void

      • Optional ReadonlyonPaperMouseEnter?: (params: PaperHoverEventParams) => void

      • Optional ReadonlyonPaperMouseLeave?: (params: PaperHoverEventParams) => void

      • Optional ReadonlyonPaperPan?: (params: PaperPanEventParams) => void

      • Optional ReadonlyonPaperPinch?: (params: PaperPinchEventParams) => void

      • Optional ReadonlyonResize?: (params: ResizeEventParams) => void

      • Optional ReadonlyonScale?: (params: ScaleEventParams) => void

      • Optional ReadonlyonTransform?: (params: TransformEventParams) => void

      • Optional ReadonlyonTranslate?: (params: TranslateEventParams) => void

      • Optional Readonlyoptions?: 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.

      • Optional Readonlyoverflow?: boolean

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

        Default

        false
        Copy

      • Optional Readonlypaper?: 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.

      • Optional ReadonlyportalSelector?: 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.

        Example

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

        Example

        // 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={...} />
        Copy

      • Optional ReadonlypreventContextMenu?: boolean

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

        Default

        true
        Copy

      • Optional ReadonlypreventDefaultBlankAction?: boolean

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

        Default

        false
        Copy

      • Optional ReadonlypreventDefaultViewAction?: boolean

        Prevents the browser default action on cell pointer events.

        Default

        true
        Copy

      • Optional ReadonlyrenderElement?: 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'].

        Example: 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>
        }
        Copy

        Example: Local component

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

      • Optional Readonly ExperimentalrenderLink?: RenderLink<any>

        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.

        Example: Global component

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

        Example: Local component

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

        Example: 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>;
        }
        Copy

      • Optional ReadonlyrouterNamespace?: any

        Namespace used to resolve router names referenced by links.

        Default

        JointJS built-in routers

      • Optional ReadonlysnapLabels?: boolean

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

        Default

        false
        Copy

      • Optional ReadonlysnapLinks?: boolean | SnapLinksOptions

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

        Default

        { radius: 15 }
        Copy

      • Optional ReadonlysnapLinksSelf?: boolean | { distance: number }

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

        Default

        false
        Copy

      • Optional Readonlystyle?: 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.

      • Optional Readonlytransform?: 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)} />
        Copy

      • Optional Readonly ExperimentaluseHTMLOverlay?: boolean

        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
        Copy

      • Optional ReadonlyvalidateConnection?: 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).

      • Optional ReadonlyvalidateEmbedding?: ValidateEmbedding

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

      • Optional ReadonlyvalidateUnembedding?: ValidateUnembedding

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

      • Optionalref?: Ref<Paper | null>

    Returns ReactNode