Diagram - Snapping

#Usage

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

<Diagram.Root :store="store" page-id="page" :aid-options="{ grid: true, rulers: true, snap: true, gridSize: 20 }">
    <Diagram.Viewport label="Workflow editor" style="height: 24rem" />
</Diagram.Root>

Configure snapping on the root. The viewport renders aids automatically; do not add a second aids renderer.

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

Editor aids are local session preferences. They help pointer placement without rewriting saved graph records or replacing explicit Arrange commands. Use the ordinary root and viewport; bind root aidOptions from your application.

#Choose grid and ruler preferences

Change the grid size, toggle Grid and Rulers, then enable Snap and move Review request. In this example geometry and port targets are disabled, so only the grid can correct the gesture.

The copied DiagramViewControlsUI consumes aidOptions and emits aidOptionsChange. The host replaces its own ref value and passes it back to the root. Grid and rulers are visual preferences; a visible grid alone does not enable snapping. The host may persist these preferences separately from the model. Reset restores this example's preferences, model and initial view.

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

const aids: DiagramAidOptions = {
    grid: true,
    rulers: true,
    snap: true,
    gridSize: 20,
    geometry: false,
    ports: false
};

Keep ref/computed option objects stable until a setting changes. Calling session.configureAids(options) is the imperative alternative; when the root input owns them, update that owner. Reconfiguration cancels the current pointer gesture and clears its guides.

#Snap to geometry and ports

Drag Review request near Approve request's edges, centers or input port. Compare Body targets and Port targets independently. Guides describe the winning target while the pointer gesture is active; release commits the corrected geometry, and Escape cancels it.

Move snapping uses the selected roots' combined world body bounds and excludes their subtrees. A single-node resize snaps its transformed corner. Drawing snaps both endpoints. Multi-node resizing does not add individual corner snaps. Measured geometry, rotation, visibility and ancestor clipping affect candidates.

session.getSnapshot().guides holds transient guides with axis, position, extent, kind and optional target ID. Grid correction stays visually quiet; geometry and port winners produce guides. Guides clear after finish, cancellation, disabling/reconfiguring aids or a tool change. They are not stored as diagram records or Undo steps. Final geometry uses the same last pointer position as the final guide correction.

#Options and limits

The session applies these defaults when the root input is an empty object:

The candidate search uses bounded geometry-index strips and target proximity. It can omit a nearer target when its budget is exhausted; it is not an exhaustive nearest-neighbor search over the page. Increasing the budget is a preference, not a performance guarantee.

Snapping applies during supported pointer edits. Numeric move or align/distribute commands perform their explicit requested operation. They do not simulate a drag or create live guides. Editor policy and target ownership still govern commit and Undo.

#Related Docs

• Drag and Drop
• Resize
• Drawing
• Overlays