Skip to content

RhythrosaLabs/streamlit-node-editor

BranchesTags

Repository files navigation

streamlit-node-editor screenshot

streamlit-node-editor

A ComfyUI / Unreal Blueprints-style node graph editor for Streamlit

PyPI version Python versions License Downloads

streamlit-node-editor is a fully interactive node graph editor that runs inside any Streamlit application. Define typed node types in Python, let users build graphs by dragging ports and connecting wires, and get the full graph state back as structured JSON — all with zero runtime dependencies beyond Streamlit (no React Flow, no external graph library).

Features

Node Graph

  • Typed ports — color-coded input/output ports with data type labels; only compatible types can connect
  • Drag-to-wire — click an output port, drag, and drop on a compatible input to create a connection
  • Type validation — incompatible connections are silently rejected, preventing invalid graphs
  • Animated wires — smooth bezier curves with flowing-dot animation connect ports visually

Node Interaction

  • Inline parameters — select dropdowns, number inputs, text inputs, and textareas rendered inside each node body
  • Drag to move — reposition nodes freely on the canvas
  • Collapse nodes — minimize nodes to save canvas space while preserving connections
  • Delete / Backspace — removes the selected node and all its connections
  • Click wire to delete — remove connections without any menu

Canvas

  • Pan + scroll-to-zoom — navigate large graphs with proper SVG coordinate transforms
  • Animated dot-grid background — subtle grid for spatial reference
  • Configurable height — set canvas height in pixels via the height parameter

Node Palette

  • Searchable palette — filterable list of all registered node types grouped by category
  • Right-click or toolbar — open the palette from the canvas context menu or the toolbar button
  • Category grouping — nodes organized by their category field

Dark Theme

  • Consistent dark UI with color-coded node headers
  • Glass-morphism panels with subtle borders
  • Designed to match Streamlit's dark mode

Installation

pip install streamlit-node-editor

Quick Start — Data Pipeline Builder

import streamlit as st
from streamlit_node_editor import st_node_editor

NODE_DEFS = {
    "CSV Source": {
        "category": "Sources",
        "headerColor": "#4ade80",
        "inputs": [],
        "outputs": [{"name": "dataframe", "type": "DATAFRAME"}],
        "params": [
            {"key": "path", "label": "File path", "type": "string", "default": "data.csv"},
            {"key": "sep",  "label": "Separator", "type": "string", "default": ","},
        ],
    },
    "Filter Rows": {
        "category": "Transform",
        "headerColor": "#38bdf8",
        "inputs":  [{"name": "df_in",  "type": "DATAFRAME"}],
        "outputs": [{"name": "df_out", "type": "DATAFRAME"}],
        "params": [
            {"key": "query", "label": "Query expr", "type": "string", "default": "value > 0"},
        ],
    },
    "Group By": {
        "category": "Transform",
        "headerColor": "#818cf8",
        "inputs":  [{"name": "df_in",  "type": "DATAFRAME"}],
        "outputs": [{"name": "df_out", "type": "DATAFRAME"}],
        "params": [
            {"key": "column", "label": "Column",    "type": "string"},
            {"key": "agg",    "label": "Aggregate", "type": "select",
             "options": ["sum", "mean", "count", "min", "max"]},
        ],
    },
    "Bar Chart": {
        "category": "Outputs",
        "headerColor": "#fb923c",
        "inputs":  [{"name": "dataframe", "type": "DATAFRAME"}],
        "outputs": [],
        "params": [
            {"key": "x", "label": "X column", "type": "string"},
            {"key": "y", "label": "Y column", "type": "string"},
        ],
    },
}

graph = st_node_editor(NODE_DEFS, height=600, key="pipeline")

if graph:
    st.subheader("Graph state")
    st.json(graph)

API Reference

st_node_editor

st_node_editor(
    node_defs: dict[str, dict],
    initial_nodes: list[dict] | None = None,
    initial_connections: list[dict] | None = None,
    height: int = 700,
    key: str | None = None,
) -> dict | None

Parameters

Parameter Type Default Description
node_defs dict[str, dict] required Node type registry. Keys are node type names, values are definition dicts. See schema below.
initial_nodes list[dict] or None [] Pre-placed nodes on the canvas.
initial_connections list[dict] or None [] Pre-existing wire connections.
height int 700 Canvas height in pixels.
key str or None None An optional key that uniquely identifies this component. Required when placing multiple editors on one page.

Return Value

Returns a dict with the full graph state after any interaction, or None before any interaction.

{
    "nodes": [
        {
            "id":     str,                # unique node ID
            "type":   str,                # node type name (key from node_defs)
            "x":      float,              # canvas X position
            "y":      float,              # canvas Y position
            "params": {key: value, ...},  # current parameter values
        },
        ...
    ],
    "connections": [
        {
            "id":       str,   # unique connection ID
            "fromNode": str,   # source node ID
            "fromPort": int,   # output port index (0-based)
            "toNode":   str,   # target node ID
            "toPort":   int,   # input port index (0-based)
        },
        ...
    ]
}

Data Structures

Node Definition

"Node Type Name": {
    "category":    str,          # palette grouping (e.g. "Sources", "Transform")
    "headerColor": str,          # hex color for the node's title bar
    "inputs": [
        {"name": str, "type": str}   # typed input ports
    ],
    "outputs": [
        {"name": str, "type": str}   # typed output ports
    ],
    "params": [
        {
            "key":     str,          # parameter key (returned in node params)
            "label":   str,          # display label inside the node
            "type":    str,          # "int" | "float" | "string" | "select" | "textarea"
            "default": any,          # optional default value
            "options": list[str],    # required when type == "select"
        }
    ],
}

Built-in Port Types

Type Color Typical Use
IMAGE green Pixel data
LATENT purple Latent tensors
MODEL orange Neural network weights
CLIP yellow Text encoders
VAE red Variational autoencoders
INT blue Integer values
FLOAT indigo Float values
STRING stone Text data
MASK teal Binary masks
ANY gray Accepts any type

Define your own types freely in node_defs — any unrecognized type string uses the ANY gray color.

Usage Examples

Pre-placing Nodes and Connections

graph = st_node_editor(
    NODE_DEFS,
    initial_nodes=[
        {"id": "n1", "type": "CSV Source",  "x": 50,  "y": 100,
         "params": {"path": "sales.csv", "sep": ","}},
        {"id": "n2", "type": "Filter Rows", "x": 350, "y": 100,
         "params": {"query": "revenue > 1000"}},
        {"id": "n3", "type": "Bar Chart",   "x": 650, "y": 100,
         "params": {"x": "month", "y": "revenue"}},
    ],
    initial_connections=[
        {"id": "w1", "fromNode": "n1", "fromPort": 0, "toNode": "n2", "toPort": 0},
        {"id": "w2", "fromNode": "n2", "fromPort": 0, "toNode": "n3", "toPort": 0},
    ],
    height=600,
    key="pipeline",
)

Executing a Pipeline from the Graph

graph = st_node_editor(NODE_DEFS, key="pipeline")

if graph and st.button("Run Pipeline"):
    nodes_by_id = {n["id"]: n for n in graph["nodes"]}

    for node in graph["nodes"]:
        node_type = node["type"]
        params = node["params"]

        if node_type == "CSV Source":
            st.info(f"Loading {params.get('path', 'data.csv')}")
        elif node_type == "Filter Rows":
            st.info(f"Filtering: {params.get('query', '')}")
        elif node_type == "Bar Chart":
            st.info(f"Charting {params.get('x')} vs {params.get('y')}")

    st.success(f"Executed {len(graph['nodes'])} nodes with {len(graph['connections'])} connections")

Image Processing Workflow

IMAGE_NODES = {
    "Load Image": {
        "category": "Input",
        "headerColor": "#4ade80",
        "inputs": [],
        "outputs": [{"name": "image", "type": "IMAGE"}],
        "params": [
            {"key": "path", "label": "Image path", "type": "string", "default": "photo.jpg"},
        ],
    },
    "Resize": {
        "category": "Transform",
        "headerColor": "#38bdf8",
        "inputs":  [{"name": "image", "type": "IMAGE"}],
        "outputs": [{"name": "image", "type": "IMAGE"}],
        "params": [
            {"key": "width",  "label": "Width",  "type": "int", "default": 512},
            {"key": "height", "label": "Height", "type": "int", "default": 512},
        ],
    },
    "Blur": {
        "category": "Effects",
        "headerColor": "#a78bfa",
        "inputs":  [{"name": "image", "type": "IMAGE"}],
        "outputs": [{"name": "image", "type": "IMAGE"}],
        "params": [
            {"key": "radius", "label": "Radius", "type": "float", "default": 2.0},
        ],
    },
    "Save Image": {
        "category": "Output",
        "headerColor": "#fb923c",
        "inputs":  [{"name": "image", "type": "IMAGE"}],
        "outputs": [],
        "params": [
            {"key": "path",   "label": "Output path", "type": "string", "default": "output.png"},
            {"key": "format", "label": "Format",      "type": "select",
             "options": ["PNG", "JPEG", "WEBP"]},
        ],
    },
}

graph = st_node_editor(IMAGE_NODES, height=500, key="image_pipeline")

Architecture

The component is built with React 18 communicating with Streamlit via the bidirectional component API (streamlit-component-lib). All rendering uses inline SVG for wires and standard HTML/CSS for nodes.

┌──────────────────────────────────────────────────────────┐
│  Python (Streamlit)                                      │
│  st_node_editor(node_defs, initial_nodes, …, key)        │
│       ↓ args                   ↑ componentValue          │
├──────────────────────────────────────────────────────────┤
│  React Frontend (iframe)                                 │
│  ┌────────────────────────────────────────────────────┐  │
│  │  Toolbar: Add Node · Delete · Zoom · Fit           │  │
│  ├─────────┬──────────────────────────────────────────┤  │
│  │ Palette │  Canvas (pan + zoom)                     │  │
│  │         │  ┌──────────┐     ┌──────────┐           │  │
│  │ Sources │  │ CSV Source│────→│Filter    │           │  │
│  │ ├─CSV   │  │ path: .. │     │ query: ..│           │  │
│  │ ├─API   │  └──────────┘     └────┬─────┘           │  │
│  │         │                        │                 │  │
│  │ Transf. │               ┌────────▼──────┐          │  │
│  │ ├─Filter│               │  Bar Chart    │          │  │
│  │ ├─Group │               │  x: ..  y: .. │          │  │
│  │         │               └───────────────┘          │  │
│  │ Outputs │                                          │  │
│  │ ├─Chart │  · · · · · · · · (dot grid) · · · · ·   │  │
│  └─────────┴──────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
  • Wire engine — SVG bezier curves with animated flowing dots; hit-test for click-to-delete
  • Port system — typed ports with color mapping; connection validation runs on drop
  • Node renderer — HTML div with color-coded header, inline param editors, and port circles
  • Pan / zoom — CSS transform on the canvas container with scroll-wheel zoom
  • State sync — every node move, add, delete, or connection change calls Streamlit.setComponentValue() with the full graph

Browser Compatibility

Browser Status
Chrome / Edge 90+ ✅ Full support
Firefox 90+ ✅ Full support
Safari 15+ ✅ Full support
Mobile browsers ⚠️ Touch drag may vary

Requirements

  • Python 3.8+
  • Streamlit ≥ 1.28.0

License

MIT — see LICENSE for details.

Links

About

ComfyUI/Blueprints-style node graph editor for Streamlit — typed ports, drag-to-connect

pypi.org/project/streamlit-node-editor

Topics

react python blueprints node-graph node-editor streamlit streamlit-component comfyui

Resources

Readme

License

MIT license
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages