reflex-xyflow 0.0.1

A Reflex custom component wrapping xyflow / React Flow (@xyflow/react) for building node-based UIs, flow charts, diagrams and graphs in pure Python.

reflex-xyflow

A Reflex custom component that wraps xyflow / React Flow (@xyflow/react, v12), so you can build node-based UIs — flow charts, diagrams, graphs, pipelines and no-code editors — in pure Python.

Status: alpha (v0.0.1). Core controlled-graph functionality works; see the roadmap.

---

Features

• Controlled graph driven entirely from Reflex server state (nodes / edges as plain dicts).
• Wrapped components: ReactFlow, Background, Controls, MiniMap, Panel, Handle, NodeResizer, NodeToolbar.
• Rich event surface: change / connect / drag / selection / pane / delete handlers, forwarded as Python event handlers.
• Pure-Python state reducers (apply_node_changes, apply_edge_changes, add_edge) that mirror React Flow's client-side helpers.
• Automatic stylesheet injection and React Flow 12 color modes (light / dark / system).

Installation

Using uv (recommended):

uv pip install reflex-xyflow

Using pip:

pip install reflex-xyflow

Quick start

import reflex as rx
import reflex_xyflow as xyflow
from reflex_xyflow import add_edge, apply_node_changes, apply_edge_changes


class State(rx.State):
    nodes: list[dict] = [
        {"id": "1", "type": "input", "data": {"label": "Start"},
         "position": {"x": 250, "y": 25}},
        {"id": "2", "data": {"label": "Middle"}, "position": {"x": 100, "y": 125}},
        {"id": "3", "type": "output", "data": {"label": "End"},
         "position": {"x": 250, "y": 250}},
    ]
    edges: list[dict] = [
        {"id": "e1-2", "source": "1", "target": "2", "animated": True},
        {"id": "e2-3", "source": "2", "target": "3"},
    ]

    @rx.event
    def on_nodes_change(self, changes: list[dict]):
        self.nodes = apply_node_changes(changes, self.nodes)

    @rx.event
    def on_edges_change(self, changes: list[dict]):
        self.edges = apply_edge_changes(changes, self.edges)

    @rx.event
    def on_connect(self, connection: dict):
        self.edges = add_edge(connection, self.edges)


def index() -> rx.Component:
    return rx.box(
        xyflow.react_flow(
            xyflow.background(variant="dots", gap=16),
            xyflow.controls(),
            xyflow.mini_map(zoomable=True, pannable=True),
            nodes=State.nodes,
            edges=State.edges,
            on_nodes_change=State.on_nodes_change,
            on_edges_change=State.on_edges_change,
            on_connect=State.on_connect,
            fit_view=True,
        ),
        width="100vw",
        height="100vh",
    )


app = rx.App()
app.add_page(index)

Sizing: ReactFlow fills its parent (width/height: 100%). Always place it inside a sized container (e.g. a rx.box with an explicit height).

Components

Component	Factory	Purpose
ReactFlow	xyflow.react_flow	The canvas; holds nodes, edges and events.
ReactFlowProvider	xyflow.react_flow_provider	Context for hooks outside the canvas.
Background	xyflow.background	Dots / lines / cross pattern.
Controls	xyflow.controls	Zoom / fit-view / lock controls.
MiniMap	xyflow.mini_map	Overview map.
Panel	xyflow.panel	Positioned overlay for toolbars.
Handle	xyflow.handle	Connection point in a custom node.
NodeResizer	xyflow.node_resizer	Resize handles for a node.
NodeToolbar	xyflow.node_toolbar	Floating toolbar on a node.

See the specification for the full prop and event catalogue, and the data model for node/edge shapes.

Demo app

A multi-page demo (Overview, Interactive, Backgrounds, Styling) lives in xyflow_demo/:

cd xyflow_demo
uv pip install -e ..        # install the component in editable mode
reflex run

Documentation

• SDD overview
• Phases & roadmap
• Specification
• Architecture
• Data model
• Implementation plan
• Tasks
• Publishing guide

Development

This project uses uv. Reproduce the Reflex custom-component layout via reflex component init or work directly in this repo:

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
ruff check .

Acknowledgements

• xyflow / React Flow by the xyflow team (MIT).
• Reflex (Apache-2.0).

License

Apache-2.0 — see LICENSE.