React quick start

Build a controlled flow diagram with React, then keep the live diagram instance for commands such as fitting the view.

One headless model powers every framework binding: the engine owns diagram behavior and the binding translates React props into that shared model. In React, GrafloriaFlow is the front door.

Prerequisites

Use React and react-dom 17, 18, or 19. The React binding requires @grafloria/engine ^0.3.0, @grafloria/renderer ^0.4.16, and @grafloria/element ^0.4.3.

1. Install the packages

In your React application, install the binding and its peer packages:

bash
Copy
npm install @grafloria/react @grafloria/element @grafloria/renderer @grafloria/engine react react-dom

2. Render a controlled diagram

Keep nodes and edges in React state. useNodesState and useEdgesState each return the current specs, a setter for your changes, and the callback that applies changes made in the canvas.

tsx
Copy
import {
  GrafloriaFlow,
  useEdgesState,
  useNodesState,
} from '@grafloria/react';

const initialNodes = [
  {
    id: 'a',
    position: { x: 60, y: 80 },
    size: { width: 180, height: 80 },
    data: { label: 'Ingest' },
  },
  {
    id: 'b',
    position: { x: 380, y: 80 },
    size: { width: 180, height: 80 },
    data: { label: 'Publish' },
  },
];

const initialEdges = [{ id: 'e1', source: 'a', target: 'b' }];

export default function App() {
  const [nodes, setNodes, onNodesChange] = useNodesState(initialNodes);
  const [edges, , onEdgesChange] = useEdgesState(initialEdges);

  return (
    <div style={{ height: '100vh' }}>
      <button
        type="button"
        onClick={() =>
          setNodes((current) => [
            ...current,
            {
              id: `node-${current.length}`,
              position: { x: 220, y: 220 },
              size: { width: 180, height: 80 },
              data: { label: 'Review' },
            },
          ])
        }
      >
        Add node
      </button>
      <GrafloriaFlow
        nodes={nodes}
        edges={edges}
        onNodesChange={onNodesChange}
        onEdgesChange={onEdgesChange}
        fitView
        plugins
        onInit={(instance) => {
          instance.fitView();
        }}
      />
    </div>
  );
}

The parent has a real height, so the canvas has space to draw. The mounted diagram shows Ingest connected to Publish, with the plugin background and navigation controls. Dragging a node sends live models through onNodesChange, which the hook converts back into React-owned specs. Clicking Add node adds Review to that controlled state. The onInit callback receives the mounted DiagramInstance and calls fitView() on it.

The third item from each state hook is intentional: pass it to the matching change prop. The setter accepts your NodeSpec[] or EdgeSpec[] updates; the change callback receives the engine's live node or link models after canvas edits.

3. Run it

Start your normal React development server and open the application. You can drag the nodes, pan and zoom the canvas, add a node, and use Fit view. The instance is null until the flow mounts, so the optional call in the button is safe before initialization.

At the end, React owns the current nodes and edges, while the onInit callback gives you the live diagram handle for imperative operations. For the React binding API, see Grafloria React.

See the React guide for the live React examples.