Diagram - API

#Import

import { Diagram, type DiagramRootHandle, type DiagramModel } from '@primeui/vue-diagram';

The namespace and flat prefixed components share the same context and registration identity. Optional capabilities use the entries in Imports.

#API

Viewport props and expose

The default viewport slot contains additional viewport content. The viewport requires a measurable height.

Handles are available through typed template refs after mount. Root getters resolve the current owners after a reload. exportSource() returns an opaque mounted viewport handle. It expires on viewport unmount. It has no public DOM fields or constructor.

Definition and host-prop parts

Definitions resolve exact types before fallback, independently for bodies and ports; the last match wins. Host-prop getters merge application refs and events. Application handlers run first. Calling event.preventDefault() skips Diagram handling. Required accessibility attributes remain Diagram-owned.

Overlay and service hosts

Composables and keys

Main and /composables export these six typed keys and their throwing accessors:

useDiagramStore(initialModel): DiagramStore requires setup or an active effect scope. It samples the model once, returns the store directly, and owns its disposal. Validation failure throws before a consumer receives a store.

Service accessors useDiagramToolbar(), useDiagramSelectionInspector(), and useDiagramExplorer() require a root descendant. useDiagramWorkspace() requires a workspace host. useDiagramPersistence() requires a persistence host. They expose readonly snapshots and bound actions. Setup reads refs through .value; templates unwrap top-level refs. Changes use flat actions such as setConnectionType(...), not assignment to snapshot refs.

Optional accessors stay in their capability entry. In particular, useDiagramPalette(): DiagramPaletteControls comes only from /palette. The portable DiagramPaletteModel retains its separate portable contract. useDiagramOutput() comes from /export. Notation inspector accessors come from the corresponding notation entry.

Store, session, and output contracts

createDiagramStore(model, options?) returns a discriminated result. Narrow on ok before reading value; failures contain diagnostics. Snapshots and records are readonly. Controlled stores use transaction proposals and explicit acknowledgements, described in Events and commands.

DiagramPersistenceSaver is exported from main for application persistence providers. The BPMN XML import handle exposes readonly canAccept; preview, accept, cancel, resolve, and text/file actions remain on that handle.

exportDiagramSvg and output controls come from /export. Detached output uses portable content. Mounted source output captures eligible in-tree Vue content. Offscreen framework content is rejected with diagnostics; automatic offscreen component staging is unsupported. See Supported profiles and Export.

#Rendered export contracts

Import rendered export controls, options, results and source types from @primeui/vue-diagram/export.

Mounted content is cloned with its captured state. Required offscreen Vue content is rejected rather than staged into another Vue tree. Keep the source mounted and stable until output settles. Source/options changes cancel preparation and invalidate prepared print output. See Export rendered templates.

#Read a contract

Props show the accepted binding value and its default. Emits show event payloads. Scoped slots supply plain readonly values and actions; context accessors expose readonly refs. Handles expose mounted component operations.

Readonly snapshots do not authorize direct model mutation. Use the documented actions, commands and transactions.

#Component names and record names

The primary entry uses DiagramNode, DiagramConnector and DiagramLabel for Vue rendering components. Import their portable interfaces as DiagramNodeRecord, DiagramConnectorRecord and DiagramLabelRecord.

import { DiagramNode, type DiagramNodeRecord } from '@primeui/vue-diagram';

const node: DiagramNodeRecord = {
    id: 'task',
    pageId: 'page',
    layerId: 'layer',
    type: 'rectangle',
    bounds: { x: 40, y: 40, width: 160, height: 80 },
    rotation: 0,
    ports: [],
    labels: []
};

The component import renders a part. The node value belongs in a model or store command. A portable port can be expressed as DiagramNodeRecord['ports'][number].

#Root bindings and readable state

Root props

Diagram.Root accepts DiagramRootProps, an exclusive value or store source intersected with DiagramRootOptions.

Optional configuration props without a declared Vue default are undefined at the binding boundary. Their effective behavior is resolved by the relevant subsystem. Root value is a one-way input, with no update:value or root model contract.

A new value reference resets history and the save baseline even when its content equals the previous model. A page-only change preserves the store. Invalid initial sources throw. Invalid later source updates emit sourceError and preserve the valid lifetime; without a handler, development reports the error through console.error.

Root emits and slots

The default slot contains definitions, viewports, and controls. The diagnostics slot receives { diagnostics } inside a root-owned alert. A custom slot can remain visible with :show-default-diagnostics="false"; license notices are independent.

#Initial-model helper

useDiagramStore(initialModel: DiagramModel): DiagramStore

Import useDiagramStore from the main entry or /composables. Call it in an active synchronous Vue setup/effect scope. It samples the plain model once, creates one store with factory defaults and disposes it with the owner after consumers detach. Invalid models throw with diagnostics. Keep a shared owner alive until all borrowing roots and controllers detach.

Use createDiagramStore(model, options) for controlled transactions, notation modules, custom limits or explicit validation handling; check its result and own successful-store disposal.

#Find the owning workflow

#Related Docs

• Architecture
• Imports

#Connector paint order

'below' is endpoint-relative owner order. 'above' paints strokes and attached decorations above bodies within each model layer, in connector model order. Rich parts, aggregate rendering and ordinary canvas picking agree. Ports, handles and default/layer captions retain their higher priority; owner captions stay with their owner. Overlay header labels retain overlay order, while body-contained fallback headers remain part of the body.

Different viewports may choose different values for one model. Changing the policy does not change the model, routes, selection or history. Output uses committed order, and policy changes invalidate pending capture and prepared print. See export.