Diagram - Symbols

#Usage

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

const registry = new DiagramSymbolRegistry();
onBeforeUnmount(() => registry.dispose());

<Diagram.Root :store="store" page-id="page" :symbols="registry">
    <Diagram.Viewport label="Workflow editor" style="height: 24rem" />
</Diagram.Root>

Create a DiagramSymbolRegistry, register each definition used by reference, and pass that registry to the root. Dispose the registry with the model owner. Embedded symbol definitions have their own portable record contract.

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

A symbol is a reusable drawing made from inert graphics. Register a definition for rendering, then create nodes that reference its ID. Nodes retain their own position, size, rotation, ports and labels.

#Built-in families

Choose a family and symbol, then Show symbol. Undo restores the previous preview node. The selectors describe your next choice; Undo changes the model without changing that choice. The catalog uses an application-owned store transaction to replace this example's preview record; it is not the recommended gateway for interactive editor insertion or updates. Use the session gateway shown under Creating a node for editor insertion.

The library factories are optional exports from @primeui/vue-diagram/palette. Each returns a DiagramSymbolLibrary with metadata and a symbols array. Import only the families your application uses. There is no automatically registered global catalog.

These are original illustrative drawings. Choosing an electrical or process symbol does not add engineering certification, execution behavior or notation validation. Domain editors have their own supported profiles.

#An original reusable symbol

The Ticket example defines a notched path, text, a transformed ellipse and a dashed tear line on a 120 × 80 intrinsic viewport. Its conservative picking boundary is a rectangle; the notch is artwork. Input and output ports provide explicit attachment points.

Choose Grow tickets 10% or Rotate tickets 15°, then Undo. The node geometry changes through the editing session. The artwork scales with the node, and its symbol ports scale from intrinsic coordinates. Registration changes have a separate lifetime and do not enter Undo history.

The graphic API supports fill, stroke, strokeWidth, strokeDash, opacity and a finite affine transform (a, b, c, d, e, f). Graphics stay clipped to the intrinsic viewport. Paths use explicit absolute M, L, H, V, C, Q and Z commands. Use nodeFill, currentColor, none, transparent, or #RGB, #RRGGBB and #RRGGBBAA paints; arbitrary CSS paints and external resources are rejected.

#Creating a node

createDiagramSymbolNode(definition, creation) validates the definition and returns a type: 'symbol' record. It saves extensions.primeuiSymbol: { id, config } and creates dynamic ports with IDs ${nodeId}:${portKey}. config supports fill, stroke and text; other safe JSON keys remain application-owned. A text override applies to every text graphic. The helper does not register the definition or insert the node.

The demos use these records in their initial models. To insert a new symbol into an existing editor through its current constraints, approval and Undo path, submit a composite command. This excerpt assumes a registered definition and an initialized root:

The following action reads the current session in a child component rendered inside Diagram.Root. In setup, context refs require .value.

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

const { session } = useDiagramContext();

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

const node = createDiagramSymbolNode(definition, {
    id: 'new-ticket',
    pageId: 'page',
    layerId: 'layer',
    bounds: { x: 0, y: 0, width: 180, height: 120 }
});
const result = session.value.connections.execute({
    kind: 'composite',
    operation: 'paste',
    nodes: [node],
    connectors: [],
    selectedIds: [node.id]
});

Use a new node ID for each insertion and inspect result.status and result.diagnostics. Existing model ports remain authoritative: changing a definition's port catalog does not add or remove saved node ports. An existing symbol port linked through primeuiSymbolPort uses the matching definition's scaled intrinsic point while that definition is available.

#Registered and embedded definitions

The left Ticket node contains a symbol reference. The right contains the same reference plus extensions.primeuiEmbeddedSymbol. Choose Remove registration: the left reports unavailable artwork, while the right uses its embedded drawing. Restore registration to recover both drawings without editing the model.

register(definition) validates, copies and freezes the definition, and returns a removal function. Registering the same ID replaces its runtime definition. An older removal function cannot remove the replacement. Update artwork demonstrates that replacement; registered artwork takes priority over embedded artwork. Removing it reveals the original embedded copy on the right.

The embedded definition must pass validation and match the reference ID. It is used only when the registry has no matching definition. Invalid registered configuration does not fall through to a second embedded definition. Missing or invalid content remains inert, shows an unavailable notice, and retains the saved payload for recovery. Keep embedded artwork in the model when it needs to travel with that model; registration code and component instances are runtime resources. Dispose the application-owned registry and store on teardown.

#Supported SVG and PNG assets

The next example imports an original envelope through the restricted SVG profile and registers an embedded static PNG. Reject unsafe SVG shows an import failure without replacing the current artwork. Reject external image shows registration validation keeping the existing PNG. Use damaged PNG shows browser decode recovery; Restore PNG supplies the valid source again.

SVG import rejects nesting, scripts, event handlers, styles, references, entities, comments and declarations. It does not import SVG image elements. Use the symbol graphic API to include a supported PNG instead. The importer supports opacity and matrix transforms; strokeDash is available in graphic definitions, not as an imported stroke-dasharray attribute.

PNG validation accepts the static container profile with IHDR, IDAT, IEND and optional PLTE/tRNS chunks. Images must be noninterlaced with standard compression/filter methods, at most 1 MiB of decoded container bytes and 4,194,304 pixels. Remote URLs, SVG data URLs, JPEG, animated PNG and unsupported chunks are rejected. Container validation is separate from browser pixel decoding: a structurally accepted but undecodable image shows Image could not be decoded. Replacing the source clears that failure after a successful load/decode.

importDiagramSymbolSvg(source, metadata) throws on an unsupported asset before registration. registry.register() also throws on an invalid definition. Catch these errors before replacing your application's valid artwork. The exported DIAGRAM_SYMBOL_LIMITS includes the other bounds: 256 graphics, 64 ports, 32,768 path characters, 1024 path commands, 131,072 SVG characters and 512 registrations. These are supported-profile limits, not an arbitrary image loader.

#Related Docs

• Shapes
• Ports
• Architecture
• Model
• Reusable palettes