React Flow is a library for building node-based graphs. You can easily implement custom node types and it comes with plugins like a mini-map and graph controls. Feel free to check out the examples or read the blog post to get started.
- Key Features
- Installation
- Usage
- ReactFlow Component Props
- Nodes
- Edges
- Helper Functions
- Plugins
- Examples
- Development
- Testing
- Easy to use: Seamless zooming & panning behaviour and single and multi-selections of elements
- Customizable: Different node and edge types and support for custom nodes and edges
- Fast rendering: only elements that are in the view port are displayed
- Utils: Snap-to-grid, background styles and graph helper functions
- Plugin system: Mini map and graph controls
- Reliable: Written in Typescript and tested with cypress
In order to make this library as flexible as possible we don’t do any state updates besides the positions. This means that you need to pass all functions that change the displayed nodes and edges by yourself. You can implement your own ones or use the helper functions that come with the library.
npm install react-flow-renderer
This is a very basic example of how to use react-flow. There are more advanced examples in the example folder.
import React from 'react';
import ReactFlow from 'react-flow-renderer';
const elements = [
{ id: '1', data: { label: 'Node 1' }, position: { x: 250, y: 5 } },
{ id: '2', data: { label: 'Node 2' }, position: { x: 100, y: 100 } },
{ id: 'e1-2', source: '1', target: '2', animated: true },
];
const graphStyles = { width: '100%', height: '100%' };
const BasicGraph = () => (
<ReactFlow elements={elements} style={graphStyles} />
);
elements
: array of nodes and edges (required)onElementClick
: element click handleronElementsRemove
: element remove handleronNodeDragStop
: node drag stop handleronConnect
: connect handleronLoad
: editor load handleronMove
: move handlernodeTypes
: object with node typesedgeTypes
: object with edge typesstyle
: css style passed to the wrapperconnectionLineType
: connection line type =straight
orbezier
connectionLineStyle
: connection style as svg attributesdeleteKeyCode
: default:8
(delete)selectionKeyCode
: default:16
(shift)showBackground
: default:true
backgroundGap
: gap size - default:16
backgroundColor
: color of dots or lines - default:#eee
backgroundType
: background type =dots
orlines
- default:dots
snapToGrid
: default:false
snapGrid
: [x, y] array - default:[16, 16]
onlyRenderVisibleNodes
: default:true
isInteractive
: default:true
. If the graph is not interactive you can't drag any nodes
There are three different node types (default
, input
, output
) you can use. You can also create custom nodes.
Node example: { id: '1', type: 'input', data: { label: 'Node 1' }, position: { x: 250, y: 5 } }
id
: string (required)position
: { x: number, y: number } (required)data
: {} (required if you are using a standard type, otherwise depends on your implementation)type
: 'input' | 'output' | 'default' or a custom one you implementedstyle
: css propertiestargetPosition
: 'left' | 'right' | 'top' | 'bottom' handle position - default: 'top'sourcePosition
: 'left' | 'right' | 'top' | 'bottom' handle position - default: 'bottom'
The standard node types are input
, default
and output
. The default node types object looks like this:
{
input: InputNode,
default: DefaultNode,
output: OutputNode
}
The keys represent the type names and the values are the node components that gets rendered.
If you want to introduce a new node type you can pass a nodeTypes
object to the React Flow component:
nodeTypes={{
special: MyCustomNode
}}
You can now use type special
for a node.
The default
, input
and output
types will be still available except you overwrite one of them.
You can find an example of how to implement a custom node in the custom node example.
There are three edge types (straight
, default
, step
) you can use. The default type is default
. You can also create custom edges.
Edge example: { id: 'e1-2', type: 'straight', source: '1', target: '2', animated: true }
id
: string (required)source
: string (an id of a node) (required)target
: string (an id of a node) (required)type
: 'input' | 'output' | 'default' or a custom one you implementedanimated
: booleanstyle
: css properties
The basic edge types are straight
, default
and step
. The default edgeTypes
object looks like this:
{
default: BezierEdge,
straight: StraightEdge,
step: StepEdge
}
The keys represents the type names and the values are the edge components.
If you want to introduce a new edge type you can pass an edgeTypes
object to the React Flow component:
edgeTypes={{
special: MyCustomEdge
}}
You can now use type special
for an edge.
The straight
, default
and step
types will be still available except you overwrite one of them.
If you want to remove a node or connect two nodes with each other you need to pass a function to onElementsRemove
or onConnect
. In order to simplify this process we are exporting some helper functions so that you don't need to implement them by yourself:
import ReactFlow, { isNode, isEdge, removeElements, addEdge } from 'react-flow-renderer';
isEdge = (element: Node | Edge): boolean
isNode = (element: Node | Edge): boolean
removeElements = (elementsToRemove: Elements, elements: Elements): Elements
addEdge = (edgeParams: Edge, elements: Elements): Elements
You can use these function as seen in this example or implement them by yourself to update your elements.
You can use the MiniMap plugin by passing it as a children to the React Flow component:
import ReactFlow, { MiniMap } from 'react-flow-renderer';
const GraphWithMiniMap = () => (
<ReactFlow
elements={elements}
>
<MiniMap />
</ReactFlow>
);
nodeColor
: string | function - if you pass a color as a string all nodes will get that color. If you pass a function you can return a color depending on the node.nodeBorderRadius
: numbermaskColor
: stringstyle
: css propertiesclassName
: class name
The control panel contains a zoom-in, zoom-out and a fit-view button. You can use it by passing it as a children to your React Flow component:
import ReactFlow, { Controls } from 'react-flow-renderer';
const GraphWithControls = () => (
<ReactFlow
elements={elements}
>
<Controls />
</ReactFlow>
);
style
: css propertiesclassName
: class name
You can find all examples in the example folder or check out the live versions:
If you want to contribute or develop some custom features the easiest way is to start the dev server:
npm run dev
This serves the content of the examples
folder and watches changes inside the src
folder. The examples are using the source of the src
folder.
Testing is done with cypress. You can find all test in the integration/flow
folder. In order to run the test do:
npm run test
Special thanks to Andy Lindemann for a lot of helpful contributions!