Flow
The declarative, AI-first flow surface — render a node/edge graph from plain serializable data.
Category: display · WCAG 2.1-AA · flow, graph, declarative, diagram, ai-first
Props
| Prop | Type | Default | Description |
|---|---|---|---|
nodes | FlowNode[] | — | Initial nodes (serializable). |
edges | FlowEdge[] | — | Initial edges (serializable). |
onNodesChange | (nodes: FlowNode[]) => void | — | Called with the next nodes when they change (drag, add, remove). |
onEdgesChange | (edges: FlowEdge[]) => void | — | Called with the next edges when they change. |
onConnect | (connection: Connection) => void | — | Called when two handles are connected to form a new edge. |
nodeTypes | Record<string, NodeRenderer> | — | Custom node renderers keyed by node.type. |
fitView | boolean | true | When true, fits the graph to the viewport on mount. |
background | boolean | FlowBackgroundProps | false | Background pattern — true for the default dots, or a config object. |
controls | boolean | false | Whether to show the controls. |
minimap | boolean | false | When true, shows the minimap overlay. |
layout | 'grid' | 'layered' | ((nodes, edges) => FlowNode[]) | — | Optional dependency-free layout. |
interactive | boolean | true | When false (view mode), nodes cannot be selected, dragged, or connected and handles are hidden; pan/zoom still work. |
className | string | — | Additional CSS class names merged onto the root element. |
activeDirection | 'forward' | 'reverse' | undefined | — | Direction the active edge's dash travels. |
activeEdgeId | string | undefined | — | Highlight + animate a single edge (used by FlowStory's active step). |
maxZoom | number | — | Maximum zoom scale the viewport can reach. |
minZoom | number | — | Minimum zoom scale the viewport can reach. |
Design tokens
--cascivo-color-bg--cascivo-color-surface--cascivo-color-accent
When to use
- Rendering a graph from data — the common case and the agent-emittable surface
- Flowcharts, DAGs, pipelines, and mind-maps from plain nodes/edges arrays
When not to use
- A scripted, sequenced walkthrough — use FlowStory
- Heavy graph editing (undo/redo, resize/rotate) — out of scope
Examples
Declarative pipeline
A flow from plain serializable data, with background, controls, and an animated edge.
() => (
<Flow
style={{ height: 280 }}
background
controls
nodes={[
{ id: 'a', position: { x: 0, y: 60 }, data: { label: 'Client' } },
{ id: 'b', position: { x: 240, y: 60 }, data: { label: 'Gateway' } },
{ id: 'c', position: { x: 480, y: 60 }, data: { label: 'Service' } },
]}
edges={[
{ id: 'ab', source: 'a', target: 'b', animated: true, label: 'request' },
{ id: 'bc', source: 'b', target: 'c' },
]}
/>
)Layered layout
Let the dependency-free layered layout arrange a small DAG.
() => (
<Flow
style={{ height: 300 }}
layout="layered"
background
minimap
nodes={[
{ id: 'a', position: { x: 0, y: 0 }, data: { label: 'Ingest' } },
{ id: 'b', position: { x: 0, y: 0 }, data: { label: 'Transform' } },
{ id: 'c', position: { x: 0, y: 0 }, data: { label: 'Validate' } },
{ id: 'd', position: { x: 0, y: 0 }, data: { label: 'Load' } },
]}
edges={[
{ id: 'ab', source: 'a', target: 'b' },
{ id: 'ac', source: 'a', target: 'c' },
{ id: 'bd', source: 'b', target: 'd' },
{ id: 'cd', source: 'c', target: 'd' },
]}
/>
)