Handles

Handles are the connection points on nodes in React Flow. Our built-in nodes include one source and one target handle, but you can customize your nodes with as many different handles as you need.

Creating a node with handles

To create a custom node with handles, you can use the <Handle /> component provided by React Flow. This component allows you to define source and target handles for your custom nodes. Here’s an example of how to implement a custom node with two handles:

import { Handle } from '@xyflow/react';
 
export function CustomNode() {
  return (
    <div className="custom-node">
      <div>Custom Node Content</div>
      <Handle type="source" position="top" />
      <Handle type="target" position="bottom" />
    </div>
  );
}

Using multiple handles

If you want to use multiple source or target handles in your custom node, you need to specify each handle with a unique id. This allows React Flow to differentiate between the handles when connecting edges.

  <Handle type="target" position="top" />
  <Handle type="source" position="right" id="a" />
  <Handle type="source" position="bottom" id="b" />

To connect an edge to a specific handle of a node, use the properties sourceHandle (for the edge’s starting point) and targetHandle (for the edge’s ending point). By defining sourceHandle or targetHandle with the appropriate handle id, you instruct React Flow to attach the edge to that specific handle, ensuring that connections are made where you intend.

const initialEdges = [
  { id: 'n1-n2', source: 'n1', sourceHandle: 'a', target: 'n2' },
  { id: 'n1-n3', source: 'n1', sourceHandle: 'b', target: 'n3' },
];

In this case, the source node is n1 for both handles but the handle ids are different. One comes from handle id a and the other one from b. Both edges also have different target nodes:

Custom handles

You can create your own custom handles by wrapping the <Handle /> component. This example shows a custom handle that only allows connections when the connection source matches a given id.

import { Handle, Position } from '@xyflow/react';
 
export function TargetHandleWithValidation({ position, source }) {
  return (
    <Handle
      type="target"
      position={position}
      isValidConnection={(connection) => connection.source === source}
      onConnect={(params) => console.log('handle onConnect', params)}
      style={{ background: '#fff' }}
    />
  );
}

Typeless handles

If you want to create a handle that does not have a specific type (source or target), you can set connectionMode to Loose in the <ReactFlow /> component. This allows the handle to be used for both incoming and outgoing connections.

Dynamic handles

If you are programmatically changing the position or number of handles in your custom node, you need to update the node internals with the useUpdateNodeInternals hook.

Custom handle styles

Since the handle is a div, you can use CSS to style it or pass a style prop to customize a Handle. You can see this in the Add Node On Edge Drop and Simple Floating Edges examples.

Styling handles when connecting

The handle receives the additional class names connecting when the connection line is above the handle and valid if the connection is valid. You can find an example which uses these classes here.

Hiding handles

If you need to hide a handle for some reason, you must use visibility: hidden or opacity: 0 instead of display: none. This is important because React Flow needs to calculate the dimensions of the handle to work properly and using display: none will report a width and height of 0!