Reference
Components
<Handle />

<Handle />

Source on GitHub (opens in a new tab)

The <Handle /> component is used in your custom nodes to define connection points.

import { Handle, Position } from '@xyflow/react';
 
export CustomNode = ({ data }) => {
  return (
    <>
      <div style={{ padding: '10px 20px' }}>
        {data.label}
      </div>
 
      <Handle type="target" position={Position.Left} />
      <Handle type="source" position={Position.Right} />
    </>
  );
};

Props

For TypeScript users, the props type for the <Handle /> component is exported as HandleProps.

#id?
string
#type
"source" | "target"
#position
The position of the handle relative to the node. In a horizontal flow source handles are typically Position.Right and in a vertical flow they are typically Position.Top.
#isConnectable?
boolean
true
#isConnectableStart?
boolean
Dictates whether a connection can start from this handle.
type === "source"
#isConnectableEnd?
boolean
Dictates whether a connection can end on this handle.
type === "target"
#onConnect?
(connection: Connection) => void
#isValidConnection?
(connection: Connection) => boolean
Called when a connection is dragged to this handle. You can use this callback to perform some custom validation logic based on the connection target and source, for example. Where possible, we recommend you move this logic to the isValidConnection prop on the main ReactFlow component for performance reasons.

Examples

Custom handle with validation

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 const TargetHandleWithValidation = ({ position, source }) => (
  <Handle
    type="target"
    position={position}
    isValidConnection={(connection) => connection.source === source}
    onConnect={(params) => console.log('handle onConnect', params)}
    style={{ background: '#fff' }}
  />
);

Style 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.

Multiple handles

If you need multiple source or target handles you can achieve this by creating a custom node. Normally you just use the id of a node for the source or target of an edge. If you have multiple source or target handles you need to pass an id to these handles. These ids can be used by an edge with the sourceHandle and targetHandle options, so that you can connect a specific handle. If you have a node with an id = 1 and a handle with an id = a you can connect this handle by using the node source=1 and the sourceHandle=a.

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.

You can find an example of how to implement a custom node with multiple handles in the custom node guide or in the custom node example.

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.

Notes

  • 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!
<EdgeText /><MiniMap />