Introduction

English | 简体中文

A highly customizable streaming flow builder. The registration ability can flexibly customize your nodes, different types of node display and form, etc.

Try it out

http://react-flow-builder.site

Github

https://github.com/bytedance/flow-builder

Installation

yarn add react-flow-builder

or

npm install react-flow-builder

Usage

// index.tsx
import React, { useState, useContext } from 'react';
import FlowBuilder, {
  NodeContext,
  INode,
  IRegisterNode,
} from 'react-flow-builder';

import './index.css';

const StartNodeDisplay: React.FC = () => {
  const node = useContext(NodeContext);
  return <div className="start-node">{node.name}</div>;
};

const EndNodeDisplay: React.FC = () => {
  const node = useContext(NodeContext);
  return <div className="end-node">{node.name}</div>;
};

const OtherNodeDisplay: React.FC = () => {
  const node = useContext(NodeContext);
  return <div className="other-node">{node.name}</div>;
};

const ConditionNodeDisplay: React.FC = () => {
  const node = useContext(NodeContext);
  return <div className="condition-node">{node.name}</div>;
};

const registerNodes: IRegisterNode[] = [
  {
    type: 'start',
    name: 'start node',
    displayComponent: StartNodeDisplay,
    isStart: true,
  },
  {
    type: 'end',
    name: 'end node',
    displayComponent: EndNodeDisplay,
    isEnd: true,
  },
  {
    type: 'node',
    name: 'other node',
    displayComponent: OtherNodeDisplay,
  },
  {
    type: 'condition',
    name: 'condition node',
    displayComponent: ConditionNodeDisplay,
  },
  {
    type: 'branch',
    name: 'branch node',
    conditionNodeType: 'condition',
  },
];

const Demo = () => {
  const [nodes, setNodes] = useState<INode[]>([]);

  const handleChange = (nodes: INode[]) => {
    console.log('nodes change', nodes);
    setNodes(nodes);
  };

  return (
    <FlowBuilder
      nodes={nodes}
      onChange={handleChange}
      registerNodes={registerNodes}
    />
  );
};

export default Demo;

// index.css
.start-node, .end-node {
  height: 64px;
  width: 64px;
  border-radius: 50%;
  line-height: 64px;
  color: #fff;
  text-align: center;
}

.start-node {
  background-color: #338aff;
}

.end-node {
  background-color: #666;
}

.other-node, .condition-node {
  width: 224px;
  border-radius: 4px;
  color: #666;
  background: #fff;
  box-shadow: 0 0 8px rgba(0, 0, 0, 0.08);
}

.other-node {
  height: 118px;
  padding: 16px;
  display: flex;
  flex-direction: column;
}

.condition-node {
  height: 44px;
  padding: 12px 16px;
}

API

FlowBuilder

Property	Description	Type	Required	Default	Version
backgroundColor	The color of background	`string`		#F7F7F7
className	The class name of the container	`string`		-
draggable	drag and drop	`boolean`		false	1.0.0
DragComponent	custom drag component	`React.FC`<DragComponent>		-	1.0.0
DropComponent	custom drop component	`React.FC`<DropComponent>		-	1.0.0
drawerProps	Extra props of Drawer Component from antd. `visible` and `onClose` have already in FlowBuilder, and {`title`: "Configuration", `width`: 480, `destroyOnClose`: true, `maskClosable`: false}	`DrawerProps`		-
drawerVisibleWhenAddNode	Drawer visible when add node	`boolean`		false
historyTool	undo and redo	`boolean` \| HistoryToolConfig		false
layout	Use vertical or horizontal layout	`vertical` \| `horizontal`		`vertical`
lineColor	The color of line	`string`		#999999
nodes	The nodes of FlowBuilder	Node[]	✓	-
readonly	Readonly mode, cannot add, remove, configure.	`boolean`		false
registerNodes	The registered nodes	RegisterNode[]	✓	-
registerRemoteNodes	The registered remote nodes	RegisterRemoteNode[]		-	1.3.0
showPracticalBranchNode	-	`boolean`	-	false	1.1.0
showPracticalBranchRemove	-	`boolean`	-	false	1.1.0
spaceX	Horizontal spacing between nodes	`number`		`16`
spaceY	Vertical spacing between nodes	`number`		`16`
zoomTool	zoom	`boolean` \| ZoomToolConfig		false
onChange	Callback function for when the data change	(nodes: Node[], changeEvent?: `string`) => void	✓	-
onHistoryChange		`(undoDisabled: boolean, redoDisabled: boolean) => void`		-
onZoomChange		`(outDisabled: boolean, value: number, inDisabled: boolean) => void`		-

HistoryToolConfig

Property	Description	Type	Default
hidden		`boolean`	false
max		`number`	10

ZoomToolConfig

Property	Type	Default
hidden	`boolean`	false
initialValue	`number`	100
min	`number`	10
max	`number`	200
step	`number`	10

DragComponent

Property	Description	Type	Version
onDragStart	The dragStart event of the custom drag component needs to call this method to set the dragged type（ dragType in BuilderContext ）	`(nodeType: string) => void`	1.0.0
onDragEnd	The dragEnd event of the custom drag component needs to call this method to clear the dragged type（ dragType in BuilderContext ）	`() => void`	1.0.0

DropComponent

Property	Description	Type	Version
onDrop	The drop event of the custom drop component needs to call this method to add the new node type	`() => void`	1.0.0

FlowBuilderInstance

Name	Description	Type
add	add node	`(node: INode, newNodeType: string) => void` \| `(newNodeType: string) => void`
history	undo, redo	`(type: 'undo' \| 'redo') => void`
remove	remove noded	`(nodes: INode \| INode[] = useContext(NodeContext)) => void`
zoom	zoom	`(type: 'out' \| 'in' \| number) => void`
closeDrawer	close drawer	`() => void`

Formatter

Name	Description	Type
buildFlatNodes	Translate to flat nodes	`(params: {registerNodes: IRegisterNode[], nodes: INode[]}) => INode[]`
buildTreeNodes	Translate to tree nodes	`(params: {nodes: INode[]}) => INode[]`
createUuid	Create uuid	`(prefix?: string) => string`

RegisterNode

Property	Description	Type	Required	Default	Version
addableComponent		`React.FC`<AddableComponent>		-
addableNodeTypes	The list of nodes that can be added below the node	`string[]`		-
addIcon	The icon in addable node list (There are already some default icons)	`ReactNode`		-
conditionMinNum	The min number of condition node	`number`		1
conditionMaxNum	The max number of condition node	`number`		-
conditionNodeType	The type of condition node	`string`		-
configComponent	The Component of configuring node form	`React.FC`<ConfigComponent>		-
configTitle	The drawer title of configuring node	`string \| ((node: INode, nodes: INode[]) => string)`		-
customRemove	Custom remove button	`boolean`		false
displayComponent	The Component of displaying node	`React.FC`<DisplayComponent>		-
initialNodeData	the initial data when add new node	`Record<string, any>`		-
isStart	Is start node	`boolean`		false
isEnd	Is end node	`boolean`		false
name	The name of node	`string`	✓	-
removeConfirmTitle	The confirmation information before deleting the node. The title of Popconfirm	`string` \| `ReactNode`		Are you sure to remove this node?
showPracticalBranchNode	-	`boolean`	-	false	1.1.0
showPracticalBranchRemove	-	`boolean`	-	false	1.1.0
type	The type of node, promise `start` is start node type and `end` is end node type	`string`	✓	-

RegisterRemoteNode

Property	Description	Type	Required	Default	Version
url	remote url	`string`	✓	-	1.3.0
cssUrl	remote css url	`string`		-	1.3.0

DisplayComponent

Property	Description	Type
node	The all information of node (NodeContext is recommended since V1)	Node
nodes	(BuilderContext is recommended since V1)	Node[]
readonly	(BuilderContext is recommended since V1)	`boolean`
remove	Remove node (useAction is recommended since V1)	`(nodes?: INode \| INode[]) => void`

ConfigComponent

Property	Description	Type
cancel	Called on cancel, used to close the drawer (useDrawer is recommended since V1)	`() => void`
node	The all information of node (NodeContext is recommended since V1)	Node
nodes	(BuilderContext is recommended since V1)	Node[]
save	Called on save node data (automatically close the drawer, no need to call cancel). FlowBuilder will set the `validateStatusError` property according to the second param (useDrawer is recommended since V1)	`(values: any, validateStatusError?: boolean) => void`

AddableComponent

Property	Description	Type
add		`(type: string) => void`
node	The all information of node (NodeContext is recommended since V1)	Node
nodes	(BuilderContext is recommended since V1)	Node[]

Node

Property	Description	Type
children	The condition nodes array of branch node, or the next flow of condition node	Node[]
configuring	Whether configuring of node. The display Component can highlight the node according to this property	`boolean`
data	The data of node	`any`
id	The unique id of node	`string`
name	The name of node. Same as the `name` of the registered node	`string`
path	The full path in FlowBuilder	`string[]`
type	The type of node. Same as the `type` of the registered node	`string`
validateStatusError	The Component of configuring node form validate failed. The display Component can highlight the node according to this property	`boolean`

Context

Added since V1

In the context of FlowBuilder the following contexts can be used

BuilderContext

Contains props and state. The following is the state:

Property	Description	Type
zoomValue	current zoom value	`number`
setZoomValue	set zoomValue	`(zoomValue: number) => void`
historyRecords	history nodes records	`INode[][]`
setHistoryRecords	set historyRecords	`(records: INode[][]) => void`
activeHistoryRecordIndex	current index in history nodes records	`number`
setActiveHistoryRecordIndex	set activeHistoryRecordIndex	`(index: number) => void`
selectedNode	current selecred node	`INode \| undefined`
setSelectedNode	set selectedNode	`(node: INode \| undefined) => void`
drawerTitle	the title of Drawer	`string`
setDrawerTitle	set drawerTitle	`(title: string) => void`
dragType	dragged node type	`string`
setDragType	set dragType	`(type: string) => void`

NodeContext

Get the data of the node where it is used. For details Node

Hooks