flow-builder lets you register your own node types in a React canvas

The registration array is the whole extension model

The mechanism that makes this library different from a fixed flow editor is the registerNodes array, and the sample in the project documentation is the clearest way to understand it. Each entry is an object with a type, a name and a displayComponent, and flags such as isStart and isEnd to mark the entry and exit nodes. A separate entry can set conditionNodeType to point at another registered type, which is how a branch node is linked to the condition node that decides its routing. The display components are ordinary React function components that read the current node from a NodeContext hook, so a node renders whatever you write for it. The consequence for an adopter is that there is no built in node vocabulary to fight with. You do not get a start node and an end node and a generic task node that you then have to restyle. You get an array you define, and the canvas renders it. The demo code shows five registrations, start, end, other, condition and branch, which is enough to build a branching flow, and the styling in the accompanying CSS shows that the look of each node is likewise yours to control.

Your state, your rendering, your forms

The FlowBuilder component takes nodes and onChange as required props, and the sample keeps the node array in React state through useState, passing a handler that logs the change and calls setNodes. That is the entire data contract, and it is worth pausing on what it means. The library is a controlled component over your graph, not a store, so persistence, undo history, dirty tracking and server synchronisation all stay in your code. The onChange callback fires on every change, which is where you would debounce a save or push a diff. The API table also lists a historyTool prop for undo and redo, taking either a boolean or a HistoryToolConfig, plus a createUuid prop, a function of an optional type string, that lets you control how node identifiers are generated, which matters if your identifiers have to be stable across sessions. Other component level props in the table include backgroundColor, defaulting to #F7F7F7, lineColor defaulting to #999999, a layout prop that switches between vertical and horizontal, a draggable boolean defaulting to false, and a readonly mode described as preventing adding, removing and configuring. The visual chrome of the canvas is therefore configuration rather than code.

Overlays are replaceable, which is where the real flexibility lives

The version column in the API table is the most informative part of the documentation, because it shows the library growing from a plain canvas into a configurable editor. Several props arrived at version 2.0.0 and are all about replacing the interface elements the builder draws around your nodes. DrawerComponent replaces the drawer used for node configuration, PopoverComponent replaces the popover, PopconfirmComponent replaces the confirmation popover, and DragComponent and DropComponent replace the drag and drop pieces. drawerProps passes extra properties to the drawer, and drawerVisibleWhenAddNode opens the drawer automatically when a node is added, defaulting to false. registerRemoteNodes, added in 1.3.0, registers nodes that come from somewhere other than your local array, and showPracticalBranchNode with its companion showPracticalBranchRemove, from 1.1.0, control the display of a convenience branch node. Putting the drawer and the popover under application control is the substantive part of the design. The configuration form for a node is where a flow editor earns its keep, and letting you mount your own form component means you can use your existing form library, your validation rules and your permission checks, rather than working around a generic one.

Installing it and rendering a first canvas

The package is published to npm under the name react-flow-builder, and the documented installation offers both package managers:

yarn add react-flow-builder

npm install react-flow-builder

A minimal integration looks like this, with the node array held in state and the registration array passed straight in:

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

The peer dependencies are react and react-dom, both at version 16 or newer, which tells you the library does not pin you to a single React generation but does set a floor. The package is built with father-build and ships a CommonJS entry at dist/index.js, an ES module entry at dist/index.esm.js and type declarations at dist/index.d.ts, so TypeScript consumers get the types without extra work. The development toolchain is worth noting too. The documentation site is built with dumi and deployed to GitHub Pages, the same page that hosts the demo, and the repository carries a Simplified Chinese version of the same documentation. Tests run through umi-test, with a coverage variant, and the project uses prettier with lint-staged and a git hook, so formatting is enforced on commit rather than left to review.

The library edits a graph, it does not run one

This is the limitation to understand before you adopt the project, and it is a big one. What you get is a canvas for authoring a flow and a set of hooks for shaping how it looks and how it is edited. What the documentation does not describe is an execution engine, a scheduler, a trigger model or a way to turn a graph into running work. If your requirement is a visual editor whose output is a configuration document consumed by something else, that split is exactly right and the library is a good fit. If your requirement is a workflow engine with retries, timers, human approval steps and a run history, the parts you still have to build are the larger half of the product. The same gap shows up in the data model. The node type in the registration array is a string, and the node content is whatever your display component reads from the node object, so the semantics of your graph live in your application rather than in a schema the library validates. Two other practical notes follow from the package metadata. The React dependency in the dev dependencies is listed as react-flow-builder at version 2.8.0, which is the version the documentation site was built against, while the published package is at 2.11.0, so the demo you read may be slightly behind the code you install. And the repository shows no GitHub releases, so there is no release note history to diff against when you upgrade.

Editorial conclusion

Adopt react-flow-builder if you are building a flow editor in React and want full control over how your node types look and how their configuration forms behave, and you are prepared to build the forms, the persistence and the execution yourself. Do not adopt it if you need a working flow runtime, since the component renders and edits the graph but the project documentation does not describe an engine that runs it. Before you start, check the versioned API table for the prop you need, because several capabilities carry version markers, and note that the peer dependency floor is React 16 or newer, so a React 18 or 19 application inherits whatever compatibility that implies.

Frequently asked questions

Official sources

1. bytedance/flow-builder on GitHub
2. Issues
3. License: MIT
4. Project website
5. README