Sub Flows: Create Nested Nodes and Grouped Workflows

When building complex node-based applications, organizing related nodes into groups can make diagrams easier to understand and manage. React Flow Sub Flows provide a powerful way to create nested node structures by placing child nodes inside parent nodes.

With sub flows, you can build grouped workflows, nested diagrams, modular automation systems, and structured visual editors without losing the flexibility of the React Flow canvas.

Whether you are developing a workflow builder, process editor, or interactive diagramming tool, understanding parent-child node relationships is essential for creating organized React Flow applications.

What Are Sub Flows in React Flow?

A sub flow is a collection of nodes organized inside a parent node. The parent acts as a container, while its child nodes represent individual steps or components within that group.

React Flow supports this relationship through the parentId property.

Sub flows allow you to:

• Group related nodes inside a parent container.
• Move multiple child nodes together.
• Build nested workflow structures.
• Connect nodes inside and outside a group.
• Create reusable sections within complex diagrams.

For example, an automation workflow might contain a parent group called "User Registration" with child nodes for form submission, email verification, and account creation.

How to Create Parent and Child Nodes in React Flow

To create a sub flow, first define a parent node and then assign its child nodes the parent's ID using parentId.

Here is a basic example:

import { ReactFlow, type Node } from '@xyflow/react';
import '@xyflow/react/dist/style.css';

const initialNodes: Node[] = [
  {
    id: 'group-1',
    type: 'group',
    position: { x: 100, y: 100 },
    style: {
      width: 400,
      height: 250,
    },
    data: { label: 'User Registration' },
  },
  {
    id: 'child-1',
    parentId: 'group-1',
    position: { x: 40, y: 60 },
    data: { label: 'Submit Form' },
  },
  {
    id: 'child-2',
    parentId: 'group-1',
    position: { x: 220, y: 60 },
    data: { label: 'Verify Email' },
  },
];

export default function Flow() {
  return (
    <div style={{ width: '100%', height: 500 }}>
      <ReactFlow
        nodes={initialNodes}
        edges={[]}
        fitView
      />
    </div>
  );
}

Important: Always define parent nodes before their children in the nodes array. This ensures React Flow can process the parent-child relationships correctly.

Understanding Parent-Relative Positioning

One important concept in React Flow sub flows is that child node positions are relative to their parent node rather than the entire canvas.

For example:

{
  id: 'child-1',
  parentId: 'group-1',
  position: {
    x: 40,
    y: 60,
  },
  data: {
    label: 'Child Node',
  },
}

In this example, the child node is positioned 40 pixels horizontally and 60 pixels vertically from the top-left corner of its parent.

When the parent moves, its child nodes move along with it while maintaining their relative positions.

This behavior makes it easier to create grouped interfaces and nested workflow structures.

Restrict Child Nodes Within the Parent Container

By default, child nodes can be positioned outside their parent container. If you want to keep them inside the group, use the extent property.

{
  id: 'child-1',
  parentId: 'group-1',
  extent: 'parent',
  position: {
    x: 40,
    y: 60,
  },
  data: {
    label: 'Child Node',
  },
}

Setting extent: 'parent' restricts the child's movement to the boundaries of its parent node.

This is especially useful for:

• Workflow group containers.
• Dashboard sections.
• Nested process diagrams.
• Visual programming environments.

Connecting Nodes Inside and Outside a Sub Flow

React Flow sub flows are not limited to isolated groups. You can create connections between child nodes inside the same parent and connect child nodes to nodes outside the group.

For example, consider a workflow containing:

• A parent group named "Payment Process".
• Child nodes for payment validation and transaction processing.
• An external node for order confirmation.

You can connect the internal steps and create an edge from the sub flow to the external node.

This makes sub flows useful for building modular workflows while keeping the overall process connected.

Understanding Edge Rendering in Sub Flows

React Flow has specific edge-rendering behavior when parent and child nodes are involved.

By default, edges are rendered below nodes. However, edges connected to a node with a parent are rendered above nodes.

You can customize edge stacking with the zIndex property.

For example:

const defaultEdgeOptions = {
  zIndex: 1,
};

<ReactFlow
  nodes={nodes}
  edges={edges}
  defaultEdgeOptions={defaultEdgeOptions}
/>

Adjusting the edge zIndex helps control how connections appear relative to nodes, which can be important when designing complex grouped diagrams.

Using Regular React Flow Nodes as Parent Containers

You do not have to use the group node type for every parent container.

React Flow also allows built-in node types, such as default, to act as parents. You can even use custom node types as parent containers.

If you want child nodes to remain fixed inside a parent, you can disable their dragging behavior:

{
  id: 'child-1',
  parentId: 'group-1',
  draggable: false,
  position: {
    x: 40,
    y: 60,
  },
  data: {
    label: 'Fixed Child',
  },
}

This is helpful when creating structured interfaces where child elements should be displayed inside a parent without being independently moved.

Practical Use Cases for React Flow Sub Flows

Sub flows are useful whenever a diagram needs logical grouping or nested organization.

1. Workflow Builders

Group related automation steps into sections such as registration, payment, notifications, and approval.

2. Software Architecture Diagrams

Organize services, databases, APIs, and infrastructure components inside application-level containers.

3. Business Process Management

Represent departments, process stages, or business operations as grouped node structures.

4. Visual Programming Tools

Create nested logic blocks where multiple operations belong to a single parent component.

5. Data Pipeline Editors

Group data sources, transformation steps, and output operations into manageable sections.

Best Practices for Building Nested React Flow Diagrams

Follow these practices to keep sub flows organized and maintainable:

• Define parent nodes before child nodes.
• Use parentId to establish parent-child relationships.
• Remember that child positions are relative to their parent.
• Use extent: 'parent' when children must stay inside containers.
• Choose appropriate parent dimensions to provide enough space for children.
• Use meaningful group labels to improve diagram readability.
• Test edge stacking when connecting nested and external nodes.

Build Better Nested Workflows with VisualFlow

Sub flows make it possible to transform complex React Flow diagrams into organized, modular structures. By combining parent-child relationships, custom nodes, and connected groups, you can build more scalable workflow editors and interactive diagramming applications.

Explore VisualFlow for creative React Flow examples, reusable node designs, workflow layouts, and inspiration for building your next visual application.