Diagram - Labels

#Usage

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

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

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

const title: DiagramLabelRecord = {
    id: 'review-title',
    text: 'Review request',
    position: { x: 0, y: 0 },
    layout: 'centered-inside'
};

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

A label is saved scene text owned by a node or connector. Each label has its own ID and text, so one owner can carry a title and several annotations. Label text is separate from node.data.title and from Vue HTML content in a node definition. The record above supplies a centered title in a node's labels array.

#Basic and multiple labels

Put labels in the owner's labels array. Use stable label IDs. The position is an anchor in the owner's local coordinate system; a node's rotation and parent transforms place that local point in the scene.

The examples register an empty content template for native-label-only node types. This suppresses the node renderer's separate fallback text (data.title or node ID) while preserving accessible node titles and the labels rendered by the viewport. The HTML comparison node keeps its own content template.

The first node has one centered title. The second has a centered title and two outside annotations. Outside labels contribute to the scene's visual bounds; they do not enlarge the node body or change its connector docking boundary.

Attach this record to a node's labels array. DiagramLabelRecord is the portable record type; Diagram.Label is a runtime part. The viewport already renders saved labels, so do not add one part per record. With layout: 'centered-inside', projection centers the label in the node and clips its displayed text to the shape instead of using the authored position as its anchor.

#Add, update or remove

Use the session's content gateway for interactive label changes. A label command adds the supplied ID or replaces the label with that ID on the owner. A remove-label command removes the identified label. These commands apply to node and connector owners and preserve the editor's content/label permissions.

Choose Update title, enter text, then Apply label action. Choose Add/update note to create the second label; applying again updates that same ID. Choose Remove note to remove it, then Undo to restore it. Attempting to remove a missing label reports the gateway outcome in the feedback area.

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();

const result = session.value.content.execute({
    kind: 'label',
    ownerId: 'owner',
    label: {
        id: 'note',
        text: 'Waiting',
        position: { x: 115, y: 150 },
        align: 'center',
        verticalAlign: 'top'
    }
});

This action belongs in a child under Diagram.Root. The complete demo shows the matching remove command and diagnostics. Replace a label with its full desired record; preserve other fields when only changing text or layout. Saved changes participate in Undo. The toolbar's text and action choices are local state until Apply runs.

#Inline editing and rollback

Click a displayed label to select its owner and that exact label in the inspector. Drag a node label to move its node. Double-click a label, or focus its edit button and press Enter, F2 or Space. The native Label text textarea edits a content draft. Enter commits, Shift+Enter adds a newline, and Escape cancels. IME composition retains the input keys until composition finishes. Undo restores a committed label; Escape restores a draft without creating a history step.

Read-only, locked or restricted owners can reject editing through the same content policy. External model changes can make a draft stale; the gateway owns that outcome rather than the application overwriting a newer saved record.

#Node alignment and rotation

Alignment locates text around its anchor. Defaults are horizontal start, vertical baseline, zero rotation and a 16-world-unit font size.

Choose horizontal and vertical alignment and a rotation, then Apply layout. The anchor remains (125, 75). Compare centered text with text starting or ending at that point. Undo restores the saved layout. An empty or non-finite rotation is rejected by the example before it submits a command.

Text uses browser measurements when available and estimates before measurement. Explicit label colors accept opaque #RGB or #RRGGBB; otherwise the theme supplies the text paint. A font, color or layout edit replaces the same label record. The demo keeps its authored size and weight while changing alignment.

#Connector path placement

A connector label can follow a routed path. path.fraction locates the anchor by approximate arc length, so 0.5 means halfway along the route rather than halfway between its endpoint coordinates.

Choose a placement and orientation, then Apply path label. Move target down changes the connector's route and the label follows it. Undo restores either saved operation. The choice fields remain local until Apply.

Normal direction is (-tangent.y, tangent.x). The label's position adds an owner-local displacement in path mode; use (0, 0) when the fraction and offsets should supply the entire placement. Label rotation adds to the chosen path orientation. A zero-length path uses its available start point and a horizontal fallback tangent. Node-only centered-inside layout does not supply connector path placement.

#Multiline text and clipping

Labels preserve newlines and spaces. They do not automatically wrap long lines to the node width. A centered-inside label clips at the node shape while outside labels can extend beyond it. The inline editor exposes the text for editing.

Compare the diamond's preformatted multiline label with the right node's wrapping HTML paragraph. Grow label node 25% changes the diamond's bounds and reveals more of its clipped text; it does not rewrite or wrap the label. Undo restores the bounds.

Use Content for a wrapping paragraph, form or component. Use labels when saved text needs scene identity, path placement and label editing. Neither choice turns arbitrary HTML into exportable scene text; see the Geometry and measurement.

#Controls and reset

Each saved change uses a content or geometry gateway. Undo uses the current command policy. Reset replaces the owned store, clears history and local choices, remounts the root and restores the original fitted view. Buttons and native editing keys provide alternatives to pointer interaction.

#Label stacking

Connector labels paint above ordinary entities in their model layer by default. Set stacking: 'owner' to keep a connector caption with its connector, matching the previous paint order. Node labels stay with their owner unless you set stacking: 'layer'; pool headers keep their overlay behavior. Higher model layers still cover lower-layer labels, and parent clipping still applies.

The active text editor appears above scene handles within the viewport. Pan, zoom and rotation update its position without changing saved label coordinates. The transient editor is excluded from saved models and output.

Read-only and restricted labels remain visible and selectable through their owner. They have no Edit action, text cursor or dedicated edit tab stop. Changes to read-only or label permissions take effect immediately; the content gateway cancels an active draft when policy changes.

Elevated labels use --p-diagram-label-surface for a small readable surface. For saved SVG, raster and print output, set theme.labelSurface to the matching opaque color, or none to omit the surface. Output inherits the export theme surface by default (white in the default theme); CSS theme values are not captured automatically.

#Related Docs

• Content
• Shapes
• Create connections
• Geometry and measurement