LitFlow: xyflow + Lit WebComponents


LitFlow is a demonstration and starter kit for using the xyflow core system with Lit WebComponents. It provides a lightweight, framework-agnostic way to build node-based UIs.

🚀 Quick Start

$3

- Node.js (v18+)
- npm or pnpm

$3

``bash
pnpm install
`

$3

`bash
./start-server.sh
`
This will start the Vite development server and open the examples runner.

📖 Usage Guide

$3

`bash
pnpm add @ghchinoy/litflow
`

$3

Import the library in your main entry point to register the custom elements:

`javascript
import '@ghchinoy/litflow';
`

Then use the component in your HTML or framework template:

`html



`

$3

You can control the flow's behavior using attributes or properties:

| Attribute | Property | Default | Description |
|-----------|----------|---------|-------------|
| show-controls | showControls | false | Show zoom/fit controls |
| show-minimap | showMinimap | false | Show the minimap |
| show-grid | showGrid | true | Show the background grid |
| nodes-draggable | nodesDraggable | true | Allow dragging nodes |
| nodes-connectable | nodesConnectable | true | Allow creating new edges |
| pan-on-drag | panOnDrag | true | Allow panning the canvas |
| zoom-on-scroll | zoomOnScroll | true | Allow zooming with mouse wheel |

$3

To create a custom node, define a Lit component using Light DOM and register it with the flow:

`javascript
import { LitElement, html } from 'lit';
import { customElement } from 'lit/decorators.js';

@customElement('my-custom-node')
class MyNode extends LitElement {
createRenderRoot() { return this; } // Required for xyflow compatibility
render() {
return html

;
}
}

// Register the type
const flow = document.querySelector('lit-flow');
flow.nodeTypes = {
...flow.nodeTypes,
'special': 'my-custom-node'
};
`

$3

LitFlow comes with a built-in Material 3 theme. You can import the design tokens and apply them to your flow:

`javascript
import { m3Tokens } from '@ghchinoy/litflow/theme';

// These tokens are automatically applied to
// but you can also use them in your own custom nodes.
`

🏗️ Architecture

LitFlow leverages @xyflow/system, the same headless core that powers React Flow and Svelte Flow.

- examples/: Contains various implementation examples.
- examples/index.html: The main entry point to browse examples.
- examples/basic/: A simple graph implementation.
- examples/multiple-handles/: Nodes with multiple input/output ports.
- examples/dynamic-interactivity/: Adding/removing nodes and edges at runtime.
- examples/subflows/: Nested nodes and parent-child relationships.
- examples/designer/: A dual-pane authoring tool with live JSON sync.
- : The root component. It initializes the XYPanZoom instance for the viewport and manages the collection of nodes and edges.
- : A reactive Lit component for individual nodes. Uses Light DOM to ensure compatibility with xyflow's system utilities (like hit-testing).
- : A connection port component. Also uses Light DOM to ensure discoverability during connection dragging.
- : A UI overlay providing zoom and fit-view controls.
- : A live overview of the flow with viewport tracking.
- store.ts: A state container using @lit-labs/signals for fine-grained, high-performance reactivity.

🛠️ Key Features


- Panning & Zooming: Full support for viewport manipulation via d3-zoom (via xyflow).
- Node Dragging: Individual nodes can be dragged, with positions synced back to the state.
- Live Inspector Designer: A comprehensive authoring example featuring a drag-and-drop palette and live JSON synchronization.
- Global Change Observability: A robust change event that fires on any graph mutation (drag, connect, delete) for external state syncing.
- Marquee Selection: Bulk select nodes and edges by dragging a selection box (Shift + Drag).
- Edge Markers: Support for arrowheads and other markers on edges.
- Manual Connections: Drag-to-connect functionality between handles with a live connection line.
- Controls & MiniMap: Built-in utility components for navigation and overview.
- Reactive Updates: Powered by @lit-labs/signals for efficient, targeted re-renders.
- Light DOM Architecture: Optimized for @xyflow/system compatibility while maintaining Lit's reactive benefits.
- Custom Node Support: Easily build complex nodes with internal state and custom Lit templates.

📖 Documentation

Explore our comprehensive documentation following the Diataxis framework:

- Tutorials: Step-by-step guides to get you started.
- Guides: Practical instructions for common tasks.
- Explanation: Deep dives into the architecture and concepts.
- Reference: Technical API documentation.
- Examples: Live interactive showcases.

- GEMINI.md: 🤖 Project conventions and technical insights for AI agents.

🛠️ Development & Publishing

$3

To build the library and generate type definitions:
`bash
pnpm run build
`
This will output the compiled files and types to the dist/ directory.

$3

The package is published under the @ghchinoy scope. To publish a new version:

1. Update the version:
`bash
pnpm version patch # or minor, major
`
2. Build the project:
`bash
pnpm run build
`
3. Publish:
`bash
pnpm publish --access public
``

🤝 Contributing

This project is an exploration of xyflow's headless capabilities. Feel free to open issues or submit PRs to improve the Lit integration!

License

LitFlow is MIT licensed.