Docs
Realtime Flow

Realtime Flow

Real-time flow diagram editor for collaborative applications

Installation

Open in

Folder structure

  • components
  • hooks
  • lib
    • supabase
1'use client'
2
3import {
4  ReactFlow,
5  ReactFlowProvider,
6  Background,
7  Controls,
8  type Node,
9  type Edge,
10  type NodeTypes,
11  type EdgeTypes,
12} from '@xyflow/react'
13import '@xyflow/react/dist/style.css'
14import type { SupabasePersistenceOptions } from '@supabase-labs/y-supabase'
15
16import { RealtimeFlowOverlay } from './realtime-flow-overlay'
17import { useRealtimeFlow } from '../hooks/use-realtime-flow'
18
19type RealtimeFlowProps = {
20  channel: string
21  className?: string
22  style?: React.CSSProperties
23  persistence?: boolean | SupabasePersistenceOptions
24  initialNodes?: Node[]
25  initialEdges?: Edge[]
26  nodeTypes?: NodeTypes
27  edgeTypes?: EdgeTypes
28  height?: string | number
29}
30
31const DEFAULT_HEIGHT = 550
32
33const RealtimeFlowContent = ({
34  channel,
35  className,
36  style,
37  persistence,
38  initialNodes,
39  initialEdges,
40  nodeTypes,
41  edgeTypes,
42  height = DEFAULT_HEIGHT,
43}: RealtimeFlowProps) => {
44  const { nodes, edges, synced, syncError, onNodesChange, onEdgesChange, onConnect } =
45    useRealtimeFlow({
46      channel,
47      persistence,
48      initialNodes,
49      initialEdges,
50    })
51
52  return (
53    <div style={{ height, position: 'relative', ...style }} className={className}>
54      <ReactFlow
55        nodes={synced ? nodes : []}
56        edges={synced ? edges : []}
57        onNodesChange={synced ? onNodesChange : undefined}
58        onEdgesChange={synced ? onEdgesChange : undefined}
59        onConnect={synced ? onConnect : undefined}
60        nodeTypes={nodeTypes}
61        edgeTypes={edgeTypes}
62        fitView
63      >
64        <Background />
65        <Controls />
66      </ReactFlow>
67      {!synced && !syncError && <RealtimeFlowOverlay status="syncing" />}
68      {!synced && syncError && <RealtimeFlowOverlay status="error" message={syncError} />}
69    </div>
70  )
71}
72
73const RealtimeFlow = (props: RealtimeFlowProps) => (
74  <ReactFlowProvider>
75    <RealtimeFlowContent {...props} />
76  </ReactFlowProvider>
77)
78
79export { RealtimeFlow }

Introduction

The Realtime Flow component provides a collaborative diagram editor powered by React Flow and Yjs. It uses @supabase-labs/y-supabase under the hood to sync diagram state across clients through Supabase Realtime.

Features

  • Real-time node and edge synchronization via Supabase Realtime broadcast
  • Drag nodes, create connections, and delete elements collaboratively
  • Optional persistence to Postgres so diagrams survive page reloads
  • Supports custom node and edge types
  • Room-based isolation for scoped collaboration

How it works under the hood

The component creates a Yjs document with two shared maps — one for nodes and one for edges — and connects it to a Supabase Realtime channel using SupabaseProvider from @supabase-labs/y-supabase. Each node and edge is stored by its ID in the respective Y.Map, enabling per-element conflict resolution.

When a user drags a node, creates a connection, or deletes an element, the change is applied to the local React Flow state and simultaneously written to the Yjs document. Remote changes from other clients are observed and applied to the local state automatically.

When persistence is enabled, the full Yjs document state is saved to a Postgres table so it can be restored when clients reconnect.

Usage

Basic usage

import { RealtimeFlow } from '@/components/realtime-flow'
 
const nodes = [
  { id: '1', position: { x: 0, y: 0 }, data: { label: 'Node A' } },
  { id: '2', position: { x: 250, y: 150 }, data: { label: 'Node B' } },
]
 
const edges = [{ id: 'e1-2', source: '1', target: '2' }]
 
export default function FlowPage() {
  return <RealtimeFlow channel="realtime-flow-demo" initialNodes={nodes} initialEdges={edges} />
}

With persistence

Enable persistence to save the diagram to your Supabase database. This requires a table to store the Yjs document state.

First, create the required table in your Supabase project:

create table yjs_documents (
  room text primary key,
  state text not null
);

Then pass persistence to the component:

import { RealtimeFlow } from '@/components/realtime-flow'
 
export default function FlowPage() {
  return (
    <RealtimeFlow
      channel="realtime-flow-demo"
      initialNodes={nodes}
      initialEdges={edges}
      persistence
    />
  )
}

You can also pass a SupabasePersistenceOptions object:

import type { SupabasePersistenceOptions } from '@supabase-labs/y-supabase'
 
const persistenceOptions = {
  table: 'yjs_documents',
  roomColumn: 'room',
  stateColumn: 'state',
  storeTimeout: 2000,
} satisfies SupabasePersistenceOptions
 
export default function FlowPage() {
  return (
    <RealtimeFlow
      channel="realtime-flow-demo"
      initialNodes={nodes}
      initialEdges={edges}
      persistence={persistenceOptions}
    />
  )
}

Using the hook for full control

If you need programmatic access to nodes and edges (e.g. adding nodes, custom node types with editable data), use the useRealtimeFlow hook directly instead of the component:

import {
  ReactFlow,
  ReactFlowProvider,
  Background,
  Controls,
  type Node,
  type Edge,
} from '@xyflow/react'
import { useRealtimeFlow } from '@/hooks/use-realtime-flow'
 
const initialNodes: Node[] = [
  { id: '1', position: { x: 0, y: 0 }, data: { label: 'Node A' } },
  { id: '2', position: { x: 250, y: 150 }, data: { label: 'Node B' } },
]
 
export default function FlowPage() {
  const { nodes, edges, synced, onNodesChange, onEdgesChange, onConnect, setNodes, setEdges } =
    useRealtimeFlow({
      channel: 'my-flow',
      initialNodes,
    })
 
  return (
    <ReactFlowProvider>
      <ReactFlow
        nodes={synced ? nodes : []}
        edges={synced ? edges : []}
        onNodesChange={synced ? onNodesChange : undefined}
        onEdgesChange={synced ? onEdgesChange : undefined}
        onConnect={synced ? onConnect : undefined}
        fitView
      >
        <Background />
        <Controls />
      </ReactFlow>
    </ReactFlowProvider>
  )
}

setNodes and setEdges accept a new array or an updater function, just like React's useState:

// Add a node
setNodes((prev) => [...prev, newNode])
 
// Update a node
setNodes((prev) => prev.map((n) => (n.id === '1' ? { ...n, data: { label: 'Updated' } } : n)))
 
// Remove a node and its connected edges
setNodes((prev) => prev.filter((n) => n.id !== '1'))
setEdges((prev) => prev.filter((e) => e.source !== '1' && e.target !== '1'))

RealtimeFlow Props

PropTypeDescription
channelstringUnique channel name used to sync diagram state between collaborators in the same session.
initialNodes?Node[]Initial nodes to populate the diagram. Only used if no existing state is found after sync.
initialEdges?Edge[]Initial edges to populate the diagram. Only used if no existing state is found after sync.
height?string | numberHeight of the flow container. Accepts a pixel number or CSS string (e.g. "100%"). Defaults to 550.
className?stringCSS class applied to the flow wrapper element.
style?React.CSSPropertiesInline styles applied to the flow wrapper element.
persistence?boolean | SupabasePersistenceOptionsPersists diagram state to Supabase so it survives page reloads. Pass true for defaults or an options object for fine-grained control.
nodeTypes?NodeTypesCustom node type definitions for React Flow.
edgeTypes?EdgeTypesCustom edge type definitions for React Flow.

useRealtimeFlow Options

OptionTypeDescription
channelstringUnique channel name used to sync diagram state between collaborators in the same session.
initialNodes?Node[]Initial nodes to populate the diagram. Only used if no existing state is found after sync.
initialEdges?Edge[]Initial edges to populate the diagram. Only used if no existing state is found after sync.
awareness?boolean | AwarenessEnables presence tracking between users. Pass false to disable or a custom Awareness instance. Defaults to true.
persistence?boolean | SupabasePersistenceOptionsPersists diagram state to Supabase so it survives page reloads. Pass true for defaults or an options object for fine-grained control.

useRealtimeFlow Return Value

PropertyTypeDescription
nodesNode[]Current nodes array, kept in sync across all connected clients.
edgesEdge[]Current edges array, kept in sync across all connected clients.
syncedbooleanWhether the initial sync has completed. Render empty state until true.
onNodesChange(changes: NodeChange[]) => voidPass directly to React Flow's onNodesChange prop.
onEdgesChange(changes: EdgeChange[]) => voidPass directly to React Flow's onEdgesChange prop.
onConnect(connection: Connection) => voidPass directly to React Flow's onConnect prop.
setNodes(nodes: Node[] | (prev: Node[]) => Node[]) => voidUpdate nodes programmatically. Changes are synced to all clients.
setEdges(edges: Edge[] | (prev: Edge[]) => Edge[]) => voidUpdate edges programmatically. Changes are synced to all clients.

SupabasePersistenceOptions

OptionTypeDefaultDescription
tablestring'yjs_documents'Name of the Postgres table used to store documents.
schemastring'public'Schema where the table is located.
roomColumnstring'room'Column used as the document identifier.
stateColumnstring'state'Column used to store the binary Yjs state.
storeTimeoutnumber1000Debounce delay (ms) before persisting changes.

Further reading