FlowDiagram

import { FlowDiagram } from "flitter-diagram";
 
FlowDiagram(props: FlowDiagramProps): Widget

FlowDiagram is the styled entry point: the headless Flow widget with React Flow's look, its four node types, its six edge types, the controls and the minimap. It accepts every Flow prop except that config is a deep partial of XyflowFlowConfig and custom is a partial override.

Option and callback names follow React Flow. Where a default is listed, it is React Flow's default too.

Imports on these pages. The examples import from the workspace packages: flitter-diagram for the engine and the style, flitter-core for widgets. After npx flitter-ui add flow-diagram, import the style (FlowDiagram, xyflow…, XyflowFlowConfig, ShapePaint) from @/components/diagram/flow-diagram, the engine (Flow, FlowController, types, layouts, helpers) from flitter-ui/diagram, and widgets from flitter-ui. See Installation.

Gestures, touch input, edge reconnection, node resizing and node toolbars are described in Interaction.

Data and appearance

FitViewOptions is { padding?, minZoom?, maxZoom?, duration?, nodes?, includeHiddenNodes? }. padding is a fraction of the nodes' bounding box and defaults to 0.1. nodes limits the fit to those ids.

PanelPosition is one of "top-left", "top-center", "top-right", "bottom-left", "bottom-center" or "bottom-right". Panels sit 15px from the pane edge.

Viewport options

translateExtent clamps every viewport change: dragging, the wheel, pinching, auto-pan, the minimap, controller calls such as setViewport, fitView and setCenter, and the initial defaultViewport once the pane has a size. When the extent is narrower or shorter than the pane at the current zoom, it is centred on that axis. It does not limit zoom; combine it with minZoom to stop users zooming out past it.

Selection and dragging

Connections

Reconnecting and resizing

React Flow has no props for resizing or toolbars. It uses the NodeResizer and NodeToolbar components, which nodesResizable, nodeResizeOptions and the nodeToolbar prop replace here.

Reconnecting also stops when nodesConnectable is false. Reconnecting and resizing both stop while interaction is locked, with the controls' lock button or controller.setInteractive(false). See Interaction for the gestures and the resize options.

Keyboard

Each option takes a key name, an array of names, or null to disable it. Names are KeyboardEvent.key values, with "Space" for the space bar. Keys typed into an input, textarea, select or editable element are ignored.

Escape cancels a connection in progress.

The editor listens for keys on the whole document. The pan key only calls preventDefault while the pointer is over the diagram, so Space still scrolls the page and presses focused buttons everywhere else.

Hit testing

Callbacks

All callbacks are optional. Mouse callbacks receive the DOM MouseEvent. On touch screens they receive a MouseEvent synthesized from the touch, with fromTouch: true set on it.

Changes

Connections

Connection is { source, target, sourceHandle, targetHandle }, with null handles when the handle has no id. A connection started from a target handle is reported source-first.

Reconnecting edges

Reconnecting does not call onConnect, onConnectStart or onConnectEnd.

Resizing nodes

ResizeParams is { x, y, width, height, direction }. x and y are the node's position, relative to its parent when it has one. direction is the sign of the pointer movement on each axis, [-1 | 0 | 1, -1 | 0 | 1].

Nodes and edges

Pane and viewport

Deleting

Change events

The editor applies every change to its controller first and then reports it. Callbacks are notifications. You never have to apply changes back for the editor to update.

type NodeChange =
  | { type: "position"; id: string; position?: XYPosition; dragging?: boolean }
  | { type: "dimensions"; id: string; dimensions: Dimensions; setAttributes?: boolean; resizing?: boolean }
  | { type: "select"; id: string; selected: boolean }
  | { type: "remove"; id: string }
  | { type: "add"; item: FlowNode; index?: number }
  | { type: "replace"; id: string; item: FlowNode };
 
type EdgeChange =
  | { type: "select"; id: string; selected: boolean }
  | { type: "remove"; id: string }
  | { type: "add"; item: FlowEdge; index?: number }
  | { type: "replace"; id: string; item: FlowEdge };

Resize changes carry setAttributes: true, which writes the new size to node.width and node.height as well as measured. A resized node keeps that fixed size from then on.

To keep your own copy of the graph, for example to save it, apply the changes to that copy:

import { applyEdgeChanges, applyNodeChanges } from "flitter-diagram";
 
FlowDiagram({
  nodes: initialNodes,
  edges: initialEdges,
  onNodesChange: (changes) => {
    store.nodes = applyNodeChanges(changes, store.nodes);
  },
  onEdgesChange: (changes) => {
    store.edges = applyEdgeChanges(changes, store.edges);
  },
});

Here store is whatever holds your app's data. Two things to avoid:

• Do not feed changes back into the controller, as in controller.setNodes(applyNodeChanges(changes, controller.nodes)). They are already applied, and an add change would insert the node twice.
• Do not pass a freshly built nodes array on every rebuild. Each new identity replaces the editor's nodes. Pass the same array, or drive changes through the controller. If you only need a snapshot, controller.toObject() returns { nodes, edges, viewport }.

Graph helpers

These pure functions take and return plain arrays. They work with or without a mounted editor.