react-digraph

Overview

A React component which makes it easy to create a directed graph editor without implementing any of the SVG drawing or event handling logic.

Important v5.0.0 Information

Version 5.0.0 is a breaking change to some of the API interfaces. Many of the component attributes are the same, and the data format is the same, but there have been some necessary changes to improve the API, make the component faster, and add new features. Many changes will be listed below in the deprecation notes section. If you notice a problem, please use the

^4.0.0

v4.x.x

Installation

npm install --save react-digraph

If you don't have the following peerDependenies, make sure to install them:

bash
npm install --save react react-dom

Usage

The default export is a component called

GraphView

onCreateNode

onCreateEdge

GraphView

type

subtype

INode

IEdge

Configuration for nodes and edges can be passed to

GraphView

nodeTypes

nodeSubtypes

edgeTypes

It is often convenient to combine these types into a configuration object that can be referred to elsewhere in the application and used to associate events fired from nodes/edges in the

GraphView

import {
  GraphView, // required
  Edge, // optional
  type IEdge, // optional
  Node, // optional
  type INode, // optional
  type LayoutEngineType, // required to change the layoutEngineType, otherwise optional
  BwdlTransformer, // optional, Example JSON transformer
  GraphUtils // optional, useful utility functions
} from 'react-digraph';

const GraphConfig =  {
  NodeTypes: {
    empty: { // required to show empty nodes
      typeText: "None",
      shapeId: "#empty", // relates to the type property of a node
      shape: (
        
          
        
      )
    },
    custom: { // required to show empty nodes
      typeText: "Custom",
      shapeId: "#custom", // relates to the type property of a node
      shape: (
        
          
        
      )
    }
  },
  NodeSubtypes: {},
  EdgeTypes: {
    emptyEdge: {  // required to show empty edges
      shapeId: "#emptyEdge",
      shape: (
        
           
        
      )
    }
  }
}
const NODE_KEY = "id"       // Allows D3 to correctly update DOM
class Graph extends Component {
  constructor(props) {
    super(props);
this.state = {
  graph: sample,
  selected: {}
}
  }
  /* Define custom graph editing methods here */
  render() {
    const nodes = this.state.graph.nodes;
    const edges = this.state.graph.edges;
    const selected = this.state.selected;
const NodeTypes = GraphConfig.NodeTypes;
const NodeSubtypes = GraphConfig.NodeSubtypes;
const EdgeTypes = GraphConfig.EdgeTypes;

return (
  <div id="graph" style="{styles.graph}">

    <graphview ref="GraphView" nodekey="{NODE_KEY}" nodes="{nodes}" edges="{edges}" selected nodetypes="{NodeTypes}" nodesubtypes="{NodeSubtypes}" edgetypes="{EdgeTypes}" onselectnode="{this.onSelectNode}" oncreatenode="{this.onCreateNode}" onupdatenode="{this.onUpdateNode}" ondeletenode="{this.onDeleteNode}" onselectedge="{this.onSelectEdge}" oncreateedge="{this.onCreateEdge}" onswapedge="{this.onSwapEdge}" ondeleteedge="{this.onDeleteEdge}/">
  </graphview>

    );
  }

}

A typical graph that would be stored in the Graph component's state looks something like this:

{
  "nodes": [
    {
      "id": 1,
      "title": "Node A",
      "x": 258.3976135253906,
      "y": 331.9783248901367,
      "type": "empty"
    },
    {
      "id": 2,
      "title": "Node B",
      "x": 593.9393920898438,
      "y": 260.6060791015625,
      "type": "empty"
    },
    {
      "id": 3,
      "title": "Node C",
      "x": 237.5757598876953,
      "y": 61.81818389892578,
      "type": "custom"
    },
    {
      "id": 4,
      "title": "Node C",
      "x": 600.5757598876953,
      "y": 600.81818389892578,
      "type": "custom"
    }
  ],
  "edges": [
    {
      "source": 1,
      "target": 2,
      "type": "emptyEdge"
    },
    {
      "source": 2,
      "target": 4,
      "type": "emptyEdge"
    }
  ]
}

For a detailed example, check out src/examples/graph.js. To run the example:

npm install
npm run serve

A webpage will open in your default browser automatically.

• To add nodes, hold shift and click on the grid.
• To add edges, hold shift and click/drag to between nodes.
• To delete a node or edge, click on it and press delete.
• Click and drag nodes to change their position.

All props are detailed below.

Props

| Prop | Type | Required | Notes | | ---------------------- | :------------------------: | :----------: | :----------------------------------------------------------: | |

nodeKey

string

true

nodes

Array

true

edges

Array

true

allowMultiselect

boolean

false

selected

object

true

selectedNodes

Array

false

selectedEdges

Array

true

nodeTypes

object

true

nodeSubtypes

object

true

edgeTypes

object

true

onSelect

func

false

allowMultiselect

onSelectNode

func

false

onCreateNode

func

true

onContextMenu

func

true

onUpdateNode

func

true

onDeleteNode

func

true

onSelectEdge

func

true

onCreateEdge

func

true

onSwapEdge

func

true

'target'

onDeleteEdge

func

true

onBackgroundClick

func

false

onArrowClicked

func

false

onUndo

func

false

onCopySelected

func

false

onPasteSelected

func

false

canDeleteNode

func

false

canCreateEdge

func

false

canDeleteEdge

func

false

canSwapEdge

func

false

afterRenderEdge

func

false

renderNode

func

false

renderNodeText

func

false

renderDefs

func

false

renderBackground

func

false

readOnly

bool

false

disableBackspace

bool

false

maxTitleChars

number

false

gridSize

number

false

gridSpacing

number

false

gridDotSize

number

false

minZoom

number

false

maxZoom

number

false

nodeSize

number

false

edgeHandleSize

number

false

edgeArrowSize

number

false

zoomDelay

number

false

zoomDur

number

false

showGraphControls

boolean

false

layoutEngineType

typeof LayoutEngineType

false

'SnapToGrid'

rotateEdgeHandle

boolean

false

centerNodeOnMove

boolean

false

initialBBox

typeof IBBox

false

graphConfig

object

false

'HorizontalTree'

nodeSizeOverridesAllowed

boolean

false

sizeOverride

nodes

'HorizontalTree'

nodeLocationOverrides

object

false

'HorizontalTree'

onCreateNode

You have access to

d3

onCreateNode

javascript
  onCreateNode = (x, y, mouseEvent) => {
    // we can get the exact mouse position when click happens with this line
    const {pageX, pageY} = mouseEvent;
    // rest of the code for adding a new node ...
  };

Prop Types:

  nodes: any[];
  edges: any[];
  minZoom?: number;
  maxZoom?: number;
  readOnly?: boolean;
  maxTitleChars?: number;
  nodeSize?: number;
  edgeHandleSize?: number;
  edgeArrowSize?: number;
  zoomDelay?: number;
  zoomDur?: number;
  showGraphControls?: boolean;
  nodeKey: string;
  gridSize?: number;
  gridSpacing?: number;
  gridDotSize?: number;
  backgroundFillId?: string;
  nodeTypes: any;
  nodeSubtypes: any;
  edgeTypes: any;
  selected: any;
  selectedNodes: INode[];
  selectedEdges: IEdge[];
  onSelect?: ({ nodes: INode[], edges: IEdge[]) => void,
  onBackgroundClick?: (x: number, y: number) => void;
  onDeleteNode: (selected: any, nodeId: string, nodes: any[]) => void;
  onSelectNode: (node: INode | null) => void;
  onCreateNode: (x: number, y: number, event: object) => void;
  onCreateEdge: (sourceNode: INode, targetNode: INode) => void;
  onDeleteEdge: (selectedEdge: IEdge, edges: IEdge[]) => void;
  onUpdateNode: (node: INode) => void;
  onSwapEdge: (sourceNode: INode, targetNode: INode, edge: IEdge) => void;
  onSelectEdge: (selectedEdge: IEdge) => void;
  onArrowClicked?: (edge: IEdge) => void;
  canDeleteNode?: (selected: any) => boolean;
  canDeleteEdge?: (selected: any) => boolean;
  canCreateEdge?: (startNode?: INode, endNode?: INode) => boolean;
  canSwapEdge?: (sourceNode: INode, targetNode: INode, edge: IEdge) => boolean;
  afterRenderEdge?: (id: string, element: any, edge: IEdge, edgeContainer: any, isEdgeSelected: boolean) => void;
  onUndo?: () => void;
  onCopySelected?: () => void;
  onPasteSelected?: () => void;
  renderBackground?: (gridSize?: number) => any;
  renderDefs?: () => any;
  renderNode?: (
    nodeRef: any,
    data: any,
    index: number,
    selected: boolean,
    hovered: boolean
  ) => any;
  renderNodeText?: (data: any, id: string | number, isSelected: boolean) => any;
  layoutEngineType?: LayoutEngineType;
  rotateEdgeHandle?: boolean;
  centerNodeOnMove?: boolean;
  initialBBox?: IBBox;
  graphConfig?: object;
  nodeSizeOverridesAllowed?: boolean;
  nodeLocationOverrides?: {[string]: {x?: number, y?:number}}

INode

| Prop | Type | Required | Notes | | ---------------------- | :------------------------: | :----------: | :-----------------------------------------------: | |

title

string

true

x

number

false

y

number

false

type

string

false

subtype

string

false

title

The

title

Element.querySelector()

CSS.escape()

IEdge

| Prop | Type | Required | Notes | | ---------------------- | :------------------------: | :----------: | :-----------------------------------------------: | |

source

string

true

title

target

string

true

title

type

string

false

handleText

string

false

handleTooltipText

string

false

title

label_from

string

false

label_to

label_to

string

false

label_from

Imperative API

You can call these methods on the GraphView class using a ref.

| Method | Type | Notes | | ------------------ | :---------------------------------------------------------: | :-------------------------------------------------------------------------: | |

panToNode

(id: string, zoom?: boolean) => void

id

panToEdge

(source: string, target: string, zoom?: boolean) => void

source

target

Deprecation Notes

| Prop | Type | Required | Notes | | -------------------- | :-------: | :--------: | :----------------------------------------: | |

emptyType

string

true

getViewNode

func

true

renderEdge

func

false

enableFocus

bool

false

transitionTime

number

false

primary

string

false

light

string

false

dark

string

false

style

object

false

gridDot

number

false

graphControls

boolean

true