Diagram - Create connections

#Usage

import { Diagram } from '@primeui/vue-diagram';

<Diagram.Root :store="store" page-id="page" connection-type="bezier" :connection-options="{ allowDangling: false }">
    <Diagram.Viewport label="Workflow editor" style="height: 24rem" />
</Diagram.Root>

Choose the path for the next connection on the root. Node endpoints and any named ports must already exist; the viewport supplies connection gestures.

This skeleton assumes an initialized store with page page. Use First Diagram for model creation, style imports and store disposal.

Start in the default Select tool. Hover or select Source to reveal its output port, then drag that port to Target's input port. The preview follows the pointer; release on the compatible target to commit one connector.

#Drag between ports

This example uses the root's default polyline path. Both ports have the same compatibility tag, flow, and opposite output/input directions. It sets connectionOptions.allowDangling: false, so dropping on empty space cannot create an unattached endpoint.

Port positions use mode: 'dynamic' with normalized fractions: (1, .5) is the source's right-center port and (0, .5) is the target's left-center port. They follow node size changes. The source tab contains the complete typed model.

You do not need to choose Connect before dragging a port. Choose Undo to remove the last committed connection. Reset removes all created edges and restores the initial Select tool, model, history and fitted view.

Ports use a 22 client CSS pixel acquisition radius by default. Set DiagramViewport.portHitRadius to change it. The radius is independent of Diagram zoom and device pixel ratio. 0 disables proximity acquisition, keeping direct controls and keyboard activation. Explicit controls take precedence over nearby ports. Diagram acquires the nearest exposed port and validates that candidate; it does not redirect a rejected connection to another nearby port.

Custom boundary buttons belong in Diagram.NodePortsDef. Wrap each native button in Diagram.Port and bind its getPortProps slot getter to give it both anchor measurement and the shared connection interaction. The custom button replaces the built-in control for its endpoint. See Ports for placement and disabled behavior.

#Choose Bézier for the next connection

Set the root's connectionType to choose newly created paths. This example starts with 'bezier'; drag the same pair of ports to see a curved connection. Choose Polyline or Bézier to change the preference for the next creation.

<Diagram.Root :store="store" page-id="page" v-model:connection-type="connectionType">
    <Diagram.Viewport label="Connections" :auto-fit="true" style="height: 24rem" />
</Diagram.Root>

In the parent setup, declare connectionType as a ref<DiagramConnectionPathType> from Vue and import the type from @primeui/vue-diagram. This named model controls the path preference, not the Diagram document.

The root defaults to 'polyline'; supported creation preferences are 'straight', 'polyline', 'orthogonal' and 'bezier'. This guide demonstrates polyline and Bézier. A preference change cancels an unfinished creation preview, leaves existing connectors unchanged and does not enter model history. Bézier Reset restores the example's Bézier preference as well as its model and controls.

Path type and port compatibility are different values. Root connectionType selects path geometry. Port connectionType: 'flow' is a free-form compatibility tag; it does not request a path named flow.

#Explicit Connect and keyboard input

Choose Connect, click the source port, then click the target port. The tool also permits node-body endpoints: click Source's body, then Target's body. Port endpoints remain tied to those ports; body endpoints attach to the computed node boundary. Choose Connect again to return to Select.

For a keyboard path using the canvas:

1. Focus the canvas with Tab. Press Enter to focus the first entity if none is focused.
2. Use arrows to focus Source, then press C to switch to Connect.
3. Press Enter to start from the focused node's body.
4. Use arrows to focus Target, then Enter to complete the connection.

For named port endpoints, choose Connect, focus a node so its ports are visible, Tab to its Connect port Output on Source button and press Enter. Focus Target, Tab to Connect port Input on Target and press Enter. The viewport's native port buttons activate the same connection session. Their accessible names use each node and port's title. Space activates a native button too.

#Preview, rejection and cancellation

The example's bounded status line reports the connector count, current session status and first diagnostic. A successful creation uses generated connector IDs; do not maintain a second connector array in the control component. If an application uses controlled store mode or connection approval, it must handle that separate host workflow before a proposal becomes a commit.

Mouse and keyboard are the representative paths in this guide. Touch, pen and assistive-technology behavior require their own device-specific checks.

#Related Docs

• First Diagram
• Resize
• Architecture
• Connection rules

#Choose connector paint order

DiagramViewport.edgeLayer defaults to 'below'. Each connector sits immediately below its highest endpoint body and can cover lower-ranked unrelated nodes. Selecting or dragging an endpoint raises its incident connectors. Clearing selection or ending the drag restores the corresponding temporary elevation. Committed front/back commands retain their normal history.

Set edgeLayer="above" to paint connector strokes and their decorations above node bodies within each authored model layer. Different viewports under one root can use different policies. Change the binding to update an existing viewport, and omit it or pass undefined to restore 'below'. Switching policy does not change routes, selection or history.

<Diagram.Viewport edge-layer="above" label="Workflow" style="height: 24rem" />

In 'above', clicking a visible stroke over a node selects the connector; clicking away from the stroke selects the node. Existing stroke hit tolerance still applies. Ports, handles, captions and interactive template content retain their dedicated targeting rules. Higher model layers still cover lower layers.

Default connector captions and explicit stacking: 'layer' captions stay above strokes. Explicit stacking: 'owner' captions stay with their connector, before a later connector at the same priority. Node labels keep their existing owner/layer behavior. Overlay pool-header labels retain overlay order; body-contained fallback headers stay with the body.