React Integration

JsPlumb has several components to assist you to integrate with React. We recommend React 17 or later, but some users have reported that they have apps running with JsPlumb in React 16. JsPlumb has been tested against React 17, React 18 and NextJS 14.0.3.

Imports ​

"dependencies":{
  "@jsplumbtoolkit/browser-ui-react":"6.71.0"
}

Quick start ​

The main component you will use is the SurfaceComponent . Let's take a quick look at how you'd use one:

import React from "react"

import { 
        MiniviewComponent, 
        SurfaceComponent, 
        ControlsComponent
}  
from '@jsplumbtoolkit/browser-ui-react';

export default function DemoComponent({someProps}) {
    
    const data = {
        nodes:[
            { id:"1", label:"1", left:50, top:50}, 
            { id:"2", label:"TWO", left:250, top:250}
        ],
        edges:[
            { source:"1", target:"2" }
        ]    
    }
    
  return <div style={{width:"100%",height:"100%"}}>
    <SurfaceComponent data={data}>
        <ControlsComponent/>
        <MiniviewComponent/>
    </SurfaceComponent>    
    </div>
        
}

In the above example the only prop we set on the SurfaceComponent was data , meaning the component uses a default Absolute layout and some default JSX for rendering nodes. The SurfaceComponent , though, is highly configurable, mainly through its viewOptions and renderOptions props. Here's the same example from before but with a few more things configured:

import React from "react"

import { 
        MiniviewComponent, 
        SurfaceComponent, 
        ControlsComponent
}  
from '@jsplumbtoolkit/browser-ui-react';

export default function DemoComponent({someProps}) {
    
    const data = {
        nodes:[
            { id:"1", label:"1", left:50, top:50}, 
            { id:"2", label:"TWO", left:250, top:250}
        ],
        edges:[
            { source:"1", target:"2" }
        ]    
    }
    
    const viewOptions = {
        nodes:{
            default:{
                jsx:(ctx) => <div style={{width:"60px", height:"60px", backgroundColor:"white", border:"1px solid black", text-align:"center"}}><h3>{ctx.data.label}</h3></div>
            }
        }
    }
    
    const renderOptions = {
        layout:{
            type:"ForceDirected"
        },
        grid:{
          size:{
            w:50, h:50
          }    
        }    
    }                  
    
  return <div style={{width:"100%",height:"100%"}}>
    <SurfaceComponent data={data} renderOptions={renderOptions} viewOptions={viewOptions}>
        <ControlsComponent/>
        <MiniviewComponent/>
    </SurfaceComponent>    
    </div>
        
}

Rendering Nodes and Groups ​

At the core of your UI will be a SurfaceComponent , which provides the canvas onto which nodes, groups and edges are drawn. In the Quickstart section above we show a couple of examples of the SurfaceComponent in action.

Each node or group in your UI is rendered as an individual component. In the first example above, we rely on JsPlumb's default JSX to render each node, but in the second we provide some JSX ourselves, although its quite simple. In a real world app your JSX will likely be more complex. As an example, consider the component we use to render nodes in the Flowchart Builder :

import * as React from 'react';

import { ShapeComponent } from "@jsplumbtoolkit/browser-ui-react"

import anchorPositions from "./anchor-positions"

export default function NodeComponent({ctx, shapeLibrary}) {

    const { vertex, toolkit } = ctx;
    const data = vertex.data;

    return <div style={{color:data.textColor}} className="flowchart-object" data-jtk-target="true">

        <ShapeComponent obj={data} shapeLibrary={shapeLibrary} showLabels={true} labelProperty="text"/>

        {anchorPositions.map(ap => <div className={"jtk-connect jtk-connect-" + ap.id} data-jtk-anchor-x={ap.x} data-jtk-anchor-y={ap.y} data-jtk-orientation-x={ap.ox}  data-jtk-orientation-y={ap.oy} data-jtk-source="true" data-jtk-port-type="source" key={ap.id}></div>)}

        <div className="node-delete node-action delete" onClick={() => toolkit.removeNode(vertex)}></div>
    </div>
}

The contents of the JSX used to render each node/group are entirely up to you.

Mapping types to JSX ​

The viewOptions prop is used to map node/group types to JSX, and to certain behaviours. For instance, this is the nodes section of the viewOptions for the flowchart builder starter app:

import { DEFAULT, newInstance } from "@jsplumbtoolkit/browser-ui"
import NodeComponent from "./NodeComponent.jsx"

const shapeLibrary = ...
const toolkit = newInstance(....)

const view = {
  nodes: {
    [DEFAULT]: {
      jsx: (ctx) => {
        return <NodeComponent ctx={ctx}  shapeLibrary={shapeLibrary}/>
      },
      // connections to/from this node can exist at any of the given anchorPositions
      anchorPositions,
      // node can support any number of connections.
      maxConnections: -1,
      events: {
        [EVENT_TAP]: (params) => {
          surface.current.stopEditingPath()
          // if zero nodes currently selected, or the shift key wasnt pressed, make this node the only one in the selection.
          if (toolkit.getSelection()._nodes.length < 1 || params.e.shiftKey !== true) {
            toolkit.setSelection(params.obj)
          } else {
          // if multiple nodes already selected, or shift was pressed, add this node to the current selection.
            toolkit.addToSelection(params.obj)
          }
        }
      }
    }
   },
}         

To map a node/group type to some JSX, you're expected to provide a function that takes ctx as argument, and returns JSX.

ctx is an object containing five things:

interface JsxContext {
    vertex: Node | Group;           // the vertex - node or group - that is being rendered by this JSX
    surface: Surface;               // the Surface widget that is rendering the vertex
    toolkit: JsPlumbToolkit;        // the underlying JsPlumbToolkit instance
    data: Record<string, any>;      // the vertex's backing data. This is just a convenience - it can be accessed via `vertex.data`
    props: Record<string, any>;     // these are any props that you passed in as the `childProps` argument to a `SurfaceComponent`. See below.    
}

As mentioned above, you can pass back arbitrary JSX from these functions.

In this view you'll also see we pass a shapeLibrary in to each component - the demonstration uses a ShapeLibrary to draw the various flowchart shapes. What you pass in to your JSX is entirely your choice - JsPlumb gives you the ctx variable and you can use it how you like.

Passing props ​

You can pass props in to the components used to render your vertices by setting them on the childProps prop of a Surface component. For instance, in the , DemoComponent - the main app - declares a random color variable in its initial state:

class DemoComponent extends React.Component {

    constructor(props) {
        super(props);
        this.toolkit = jsPlumbToolkit.newInstance();
        this.state = { color:randomColor() };
       
    }
    
}

In the render method of the DemoComponent , a surface component is created, and the color member of the main component's state is passed in:

render() {
    return <div style={{width:"100%",height:"100%",display:"flex"}}>
        <button onClick={this.changeColor.bind(this)} style={{backgroundColor:this.state.color}} className="colorButton">Change color</button>
        <SurfaceComponent childProps={{color:this.state.color}} renderOptions={this.renderOptions} toolkit={this.toolkit} view={this.view} />
    </div>
}

In the view for the DemoComponent , each of the node types references the Surface's childProps by way of the context they are given:

this.view = {
    nodes: {
        "shin":{
            jsx: (ctx) => { return <ShinBoneComponent color={ctx.props.color} ctx={ctx}/> }
        },
        "knee":{
            jsx: (ctx) => { return <KneeBoneComponent color={ctx.props.color} ctx={ctx}/> }
        }
    },
    ...
}

So, here, ctx.props.color is referencing this.state.color in DemoComponent . If we change DemoComponent 's state, the change propagates through to the vertex components:

changeColor() {
    const current = this.state.color;
    let col;
    while (true) {
        col = randomColor();
        if (col !== current) {
            break;
        }
    }
    this.setState({ color:col } )
}

Context and Providers ​

JsPlumb React 6.40.0 has support for React's concepts of Context and Providers , and this offers a means for you to build apps with JsPlumb with far less boilerplate than was previously required. In the component discussions above you can see how MiniviewComponent and ControlsComponent can be nested inside a SurfaceComponent , and also how PaletteComponent was nested inside a SurfaceProvider - these are examples of providers and context in action.

For a primer on providers and context you can check out the React docs .

A Context is a means for some component to provide data to all of its descendants. JsPlumb React has two.

JsPlumbContext ​

This context contains an instance of the JsPlumb Toolkit - the underlying data model. A JsPlumbContext is created when a JsPlumbProvider is declared in your JSX. It's not as common to need a JsPlumbContext as it is to need a SurfaceContext : it's typically only needed in apps that wish to render one data model to more than one canvas.

SurfaceContext ​

This context contains a Surface. A SurfaceContext is created when:

In the component examples above, we see the MiniviewComponent and ControlsComponent declared without any props, as children of a SurfaceComponent . The SurfaceComponent populates a SurfaceContext with the surface it has created, and the MiniviewComponent and ControlsComponent discover the surface via the SurfaceContext :

<SurfaceComponent renderOptions={renderOptions}>
    <ControlsComponent/>
    <MiniviewComponent/>
</SurfaceComponent>

SurfaceProvider ​

This provider offers a means for you to share a surface located somewhere in your UI with other components that are not necessarily descendants of the surface component. A common use case is for Inspectors and Palettes - often you'll find they do not exist as children of the surface element but rather elsewhere in the DOM, for instance:

<div className="row">
  <SurfaceProvider>
    <div className="col-9">
      <SurfaceComponent/>
    </div>
    <div className="col-3 d-flex flex-column">
      <PaletteComponent selector="li" dataGenerator={dataGenerator} typeExtractor={typeExtractor}>
        <ul>
          <li data-node-type="foo" jtk-is-group="true">FOO</li>
          <li data-node-type="bar">BAR</li>
        </ul>
      </PaletteComponent>
      <InspectorComponent/>
    </div>
  </SurfaceProvider>
</div>  

Here we see a UI using Bootstrap , consisting of a surface across 9 columns, and then a right hand pane containing a palette and an inspector. The SurfaceProvider is a common parent for all of the JsPlumb components.

JsPlumbProvider ​

This provides a JsPlumbContext - a typical use case is when you want to render some data model to more than one place.

<div className="row">
  <JsPlumbProvider>
    <div className="col-6">
      <SurfaceComponent/>
    </div>
    <div className="col-6">
      <SurfaceComponent/>
    </div>    
  </JsPlumbProvider>
</div>  

Shape libraries ​

A shape library is a set of named shapes that you will use to render SVG inside the vertices in your application. These are discussed in detail in the shape libraries and shape-sets pages; here we provide an overview of the available React integration with these modules.

Creating a shape library ​

In React, a shape library is created the same way as in vanilla js. In the code below we create a shape library with flowchart and basic shapes, which we then inject into our SurfaceComponent :

import React from 'react';
import { FLOWCHART_SHAPES, BASIC_SHAPES, ShapeLibraryImpl, DEFAULT } from "@jsplumbtoolkit/browser-ui"

import NodeComponent from './node-component'

export default function FlowchartComponent() {
     
    const shapeLibrary = new ShapeLibraryImpl([FLOWCHART_SHAPES, BASIC_SHAPES])
    
    const viewOptions = {
        nodes: {
            [DEFAULT]: {
                jsx: (ctx) => {
                    return <NodeComponent ctx={ctx} />
                }                    
            }
        }
    }
    
    return <div>   
            <SurfaceComponent viewOptions shapeLibrary={shapeLibrary}/>
           </div>

Rendering an SVG shape ​

Shapes can be rendered with a ShapeComponent . This takes the ctx that JsPlumb passes into your JSX inside the view as a prop, from which it can extract the current vertex and the underlying surface, plus the shape library the surface is using:

import * as React from 'react';

import { ShapeComponent } from "@jsplumbtoolkit/browser-ui-react"

export default function NodeComponent({ctx}) {

    return <div className="my-class">
        <ShapeComponent ctx={ctx} />
    </div>
}

By default the shape component will render just the shape. If you want to add labels you can do so like this:

import * as React from 'react';

import { ShapeComponent } from "@jsplumbtoolkit/browser-ui-react"

export default function NodeComponent({ctx}) {

    return <div className="my-class">
        <ShapeComponent ctx={ctx} showLabels={true} labelProperty="text"/>
    </div>
}

The full list of props is available below .

Adding your own shapes ​

To add your own shapes, you'll need to create a shape set. These are discussed on a separate page .

Dragging new nodes/groups ​

Palettes offer a means for your users to drag new nodes/groups onto your canvas. The PaletteComponent is the main component you'll use; there's also a ShapeLibraryPaletteComponent which is a specialised version of the PaletteComponent that sources its draggable nodes from a ShapeLibrary .

HTML elements ​

To configure your UI to drag and drop HTML elements onto your canvas, you'll use a PaletteComponent . Here's how to set one up:

import { PaletteComponent, SurfaceComponent, SurfaceProvder } from '@jsplumbtoolkit/browser-ui-react';

export default function MyApp() {
    
  const dataGenerator = function (type) { return { w:120, h:80, type:el.getAttribute("data-node-type") } };
       
  return <div className="row">
            <SurfaceProvider>
                <div className="col-9">
                  <SurfaceComponent/>
                </div>
                <div className="col-3">
                    <PaletteComponent selector="li" dataGenerator={dataGenerator}>
                        <ul>
                            <li data-node-type="foo" jtk-is-group="true">FOO</li>
                            <li data-node-type="bar">BAR</li>
                        </ul>
                    </PaletteComponent>
                </div>
            </SurfaceProvider>
            </div>    
}

The basic contract is that you declare a PaletteComponent in your JSX, and you provide - at the minimum - a selector , which tells the palette component how to find which children of the component are draggable. You then write out the children however you like - in this case we use a ul and an li for each draggable type.

The PaletteComponent needs to know which surface it is going to be attached to, and it does this by being context aware - in the code above we have a SurfaceProvider wrapping both the surface component and the palette component. When the surface component is instantiated, it populates the surface provider's context, and the palette component is notified of the surface to use.

In the code above we also see a dataGenerator prop: dataGenerator provides a means for the component to generate an initial data payload for some node that is being dragged. You can read about the full list of available props in the component list below .

SVG shapes ​

To drag and drop SVG shapes, you can use a ShapeLibraryPaletteComponent . This is a specialised version of the PaletteComponent which sources its draggable nodes from a ShapeLibrary .

import React, { useEffect, useRef} from 'react';
import { FLOWCHART_SHAPES, BASIC_SHAPES, ShapeLibraryImpl } from "@jsplumbtoolkit/browser-ui"
import { ShapeLibraryPaletteComponent, SurfaceComponent, SurfaceProvider } from "@jsplumbtoolkit/browser-ui-react"

export default function FlowchartComponent() {

    const shapeLibrary = new ShapeLibraryImpl([FLOWCHART_SHAPES, BASIC_SHAPES])
    const dataGenerator = function (type) { return { w:120, h:80, type:el.getAttribute("data-node-type") } };
          
    return <div>
            <SurfaceProvider>
                <SurfaceComponent viewOptions={viewOptions} shapeLibrary={shapeLibrary}/>
                <ShapeLibraryPaletteComponent className="node-palette" 
                         dataGenerator={dataGenerator} initialSet={FLOWCHART_SHAPES.id}/>
            </SurfaceProvider>
    
        </div>

As with PaletteComponent , the ShapeLibraryPaletteComponent is context aware and can locate the surface to use from a SurfaceProvider .

Component List ​

This is a full list of the components that are available in JsPlumb React. For each we provide a sample usage, which does not necessarily use all of the props available for the given component. We then provide the full list of available props.

SurfaceComponent ​

The key UI component you'll use to render your UI.

<SurfaceComponent renderOptions={someRenderOptions} 
                    viewOptions={someViewOptions}/>

Interface SurfaceComponentProps

MiniviewComponent ​

Provides a Miniview of the contents of some surface. This component can be nested inside a SurfaceComponent , from which it will find the surface to attach to, or it can also exist as a descendant of a SurfaceProvider - the approach you choose will depend on the structure of your page.

Example ​

export default function MyComponent() {
    return <SurfaceComponent renderOptions={renderOptions}>
        <MiniviewComponent/>
        </SurfaceComponent>
}

Interface MiniviewComponentProps

ControlsComponent ​

Provides a component that offers a set of controls for some surface. If there is a lasso plugin installed on the given surface this component will show buttons for pan/select mode, otherwise it will not. This component can be nested inside a SurfaceComponent , from which it will find the surface to attach to, or it can also exist as a descendant of a SurfaceProvider - the approach you choose will depend on the structure of your page.

Example ​

export default function MyComponent() {
    return <SurfaceComponent renderOptions={renderOptions}>
        <ControlsComponent/>
        </SurfaceComponent>
}

Props ​

Interface ControlsComponentProps

ExportControlsComponent ​

Provides a component that offers a set of buttons users can click to generate SVG, PNG or JPG output of the canvas.

Example ​

export default function MyComponent() {
    return <SurfaceComponent renderOptions={renderOptions}>
        <ExportControlsComponent/>
        </SurfaceComponent>
}

Props ​

Interface ExportControlsComponentProps

PaletteComponent ​

Provides a means to implement drag/drop of new Nodes/Groups onto your Surface. This component can be nested inside a SurfaceComponent , from which it will find the surface to attach to, or it can also exist as a descendant of a SurfaceProvider - the approach you choose will depend on the structure of your page.

Example ​

import { PaletteComponent, SurfaceComponent, SurfaceProvder } from '@jsplumbtoolkit/browser-ui-react';

export default function MyApp() {
    
    const typeExtractor = function(el) { return el.getAttribute("data-node-type") };
    const dataGenerator = function (type) { return { w:120, h:80 }; };
       
    return <div className="row">
            <SurfaceProvider>
                <div className="col-9">
                  <SurfaceComponent/>
                </div>
                <div className="col-3">
                    <PaletteComponent selector="li" dataGenerator={dataGenerator} typeExtractor={typeExtractor}>
                        <ul>
                            <li data-node-type="foo" jtk-is-group="true">FOO</li>
                            <li data-node-type="bar">BAR</li>
                        </ul>
                    </PaletteComponent>
                </div>
            </SurfaceProvider>
            </div>    
}

Props ​

Interface PaletteComponentProps

ShapeLibraryPaletteComponent ​

This is a specialised version of the PaletteComponent which sources its draggable nodes from a ShapeLibrary .

Example ​

import React, { useEffect, useRef} from 'react';
import { FLOWCHART_SHAPES, BASIC_SHAPES, ShapeLibraryImpl } from "@jsplumbtoolkit/browser-ui"
import { ShapeLibraryPaletteComponent, SurfaceComponent, SurfaceProvider } from "@jsplumbtoolkit/browser-ui-react"

export default function FlowchartComponent() {

    const shapeLibrary = new ShapeLibraryImpl([FLOWCHART_SHAPES, BASIC_SHAPES])
    const dataGenerator = function (type) { return { w:120, h:80, type:el.getAttribute("data-node-type") } };
          
    return <div>
            <SurfaceProvider>
                <SurfaceComponent viewOptions={viewOptions}/>
                <ShapeLibraryPaletteComponent className="node-palette" 
                        shapeLibrary={shapeLibrary} dataGenerator={dataGenerator} initialSet={FLOWCHART_SHAPES.id}/>
            </SurfaceProvider>
    
        </div>

Props ​

Interface ShapeLibraryPaletteComponentProps

ShapeComponent ​

This component is used in conjunction with a ShapeLibrary to render SVG shapes.