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).

Requirements

Upgrading from 0.0.1: 0.1.0 drops Python 3.10 and requires Reflex 0.10+. Enums are now enum.StrEnum, so str(Position.TOP) returns "top".

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

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 --python 3.12 && source .venv/bin/activate
uv pip install -e ".[dev]"
ruff check . && ruff format --check .
pytest

Releases are published to PyPI automatically by the release workflow when a vX.Y.Z tag is pushed on main — see the publishing guide.

Acknowledgements

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

License

Apache-2.0 — see LICENSE.