> ## Documentation Index
> Fetch the complete documentation index at: https://crystalflow.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Workflow Builder UI
> Build visual workflow interfaces with React
The CrystalFlow React package provides components to create visual workflow builder interfaces powered by React Flow.
## Overview
The `@crystalflow/react` package includes:
Complete workflow editor component
React hooks for workflow management
Customizable node renderers
Property panels and toolbars
## Installation
```bash theme={null}
npm install @crystalflow/react @crystalflow/core reflect-metadata react react-dom
```
## Basic Usage
```tsx App.tsx theme={null}
import React from 'react';
import { WorkflowBuilder } from '@crystalflow/react';
import { AddNode, MultiplyNode } from './nodes';
function App() {
return (
{
console.log('Workflow updated:', workflow);
}}
/>
);
}
export default App;
```
## WorkflowBuilder Props
Array of node classes to make available in the palette
Optional initial workflow to load
Callback when workflow changes
Callback when workflow executes
Show/hide the toolbar
Show/hide the node palette
Show/hide the property panel
## Complete Example
```tsx theme={null}
import React, { useState } from 'react';
import { WorkflowBuilder } from '@crystalflow/react';
import {
NumberInputNode,
AddNode,
MultiplyNode,
DisplayNode
} from './nodes';
function App() {
const [workflow, setWorkflow] = useState(null);
return (
{
setWorkflow(wf);
console.log('Workflow updated');
}}
onExecute={(result) => {
console.log('Execution result:', result);
if (result.status === 'success') {
alert('Workflow executed successfully!');
} else {
alert(`Execution failed: ${result.error?.message}`);
}
}}
showToolbar={true}
showNodePalette={true}
showPropertyPanel={true}
/>
);
}
export default App;
```
## Using Custom Hooks
For more control, use the underlying hooks:
```tsx theme={null}
import React from 'react';
import {
useWorkflow,
useNodeRegistry,
useExecution
} from '@crystalflow/react';
function CustomWorkflowEditor() {
const { workflow, addNode, removeNode, connect } = useWorkflow();
const { registry } = useNodeRegistry([AddNode, MultiplyNode]);
const { execute, isExecuting, result } = useExecution();
const handleAddNode = (nodeType: string) => {
addNode(nodeType, {
position: { x: 100, y: 100 }
});
};
const handleExecute = async () => {
const executionResult = await execute(workflow);
console.log('Result:', executionResult);
};
return (
handleAddNode('math.add')}>
Add Math Node
{isExecuting ? 'Executing...' : 'Execute Workflow'}
{/* Render workflow canvas */}
);
}
```
## Node Palette
The node palette allows users to drag and drop nodes:
```tsx theme={null}
import { NodePalette } from '@crystalflow/react';
{
workflow.addNodeByType(nodeType, { position });
}}
/>
```
## Property Panel
The property panel displays node properties and inputs:
```tsx theme={null}
import { PropertyPanel } from '@crystalflow/react';
{
selectedNode.setInputValue(propertyName, value);
}}
/>
```
## Toolbar Actions
**Work in Progress:** Some toolbar features are still under development.
```tsx theme={null}
import { Toolbar } from '@crystalflow/react';
{
const json = serializeWorkflow(workflow.toJSON());
// Save to file/API
}}
onLoad={() => {
// Load from file/API
}}
onExecute={() => {
// Execute workflow
}}
onClear={() => {
// Clear workflow
}}
/>
```
## Customizing Appearance
### Custom Node Renderer
```tsx theme={null}
import { CustomNode } from '@crystalflow/react';
(
```
## Event Handling
Handle workflow events:
```tsx theme={null}
console.log('Node added:', node)}
onNodeRemove={(nodeId) => console.log('Node removed:', nodeId)}
onConnectionCreate={(conn) => console.log('Connected:', conn)}
onConnectionRemove={(conn) => console.log('Disconnected:', conn)}
onNodeSelect={(node) => console.log('Node selected:', node)}
/>
```
## Keyboard Shortcuts
**Work in Progress:** Keyboard shortcuts are planned for a future release.
Planned keyboard shortcuts:
* `Delete` - Remove selected nodes
* `Ctrl/Cmd + Z` - Undo
* `Ctrl/Cmd + Shift + Z` - Redo
* `Ctrl/Cmd + S` - Save workflow
* `Ctrl/Cmd + E` - Execute workflow
## Persistence
Save and load workflows:
```tsx theme={null}
import { serializeWorkflow, deserializeWorkflow } from '@crystalflow/core';
// Save
const saveWorkflow = () => {
const json = serializeWorkflow(workflow.toJSON());
localStorage.setItem('workflow', json);
};
// Load
const loadWorkflow = () => {
const json = localStorage.getItem('workflow');
if (json) {
const workflowData = deserializeWorkflow(json);
const loadedWorkflow = Workflow.fromJSON(workflowData);
// Set workflow in UI
}
};
```
## Monaco Editor Integration
**Work in Progress:** Monaco JSON editor integration is under development for dual-mode editing (visual + code).
Planned features:
* Side-by-side visual and JSON editing
* Real-time sync between modes
* JSON schema validation
* Syntax highlighting
## Best Practices
Use descriptive labels and categories to help users find nodes.
Show user-friendly error messages when execution fails.
Implement auto-save to prevent data loss.
Validate workflows before execution and show validation errors.
Show execution progress and node states during workflow execution.
## Example Projects
Check out complete example projects in the repository:
* **Simple Math Workflow** - Basic arithmetic operations
* **Data Processing Pipeline** - Fetch, filter, transform data
* **API Integration** - HTTP requests and response handling
## Next Steps
Complete WorkflowBuilder reference
All available React hooks
Individual component docs
View complete examples