Diagram - Value and store
Start with a value, understand who owns edits, and choose a supplied store when your application needs one.
#A value already has a store
Diagram uses a store for the current model, transactions, and Undo history. With value, the root creates and disposes that store. The root also owns a session for selection, tools, zoom, and pan.
A basic editor supplies data. It can omit pages and layers from DiagramModelInput; construction expands the input into a complete model. Pages and layers remain available when the document needs them.
Supply exactly one of value or store. Both sources together, neither source, and null are invalid. undefined means an absent source. An existing complete DiagramModel remains valid input.
#Editing is different from replacing a value
A stable value reference initializes an editor. Accepted edits change the root-owned store and produce commit events. They do not mutate the original input.
A different value reference requests a reload. Reloading resets history, the saved baseline, selection, and view initialization. Use a replacement to load another file or reset a document. Keep commit snapshots separate from the value binding.
<script setup lang="ts">
import { shallowRef } from 'vue';
import { Diagram, type DiagramModel, type DiagramReadonly, type DiagramModelInput } from '@primeui/vue-diagram';
const initialValue: DiagramModelInput = {
nodes: [{ id: 'task', type: 'task', bounds: { x: 40, y: 40, width: 180, height: 100 } }]
};
const latestCommit = shallowRef<DiagramReadonly<DiagramModel> | null>(null);
</script>
<template>
<Diagram.Root :value="initialValue" @commit="latestCommit = $event.model">
<Diagram.Viewport label="Tasks" style="height: 24rem" />
<output>{{ latestCommit ? `${latestCommit.nodes.length} committed nodes` : 'No edits yet' }}</output>
</Diagram.Root>
</template>Assigning every commit model back to value reloads the editor after each edit and resets Undo history. React onCommit={event => setValue(event.model)} has that effect when value uses the same state. Vue Root does not support v-model. Angular uses the same one-way reload contract.
An unchanged reference preserves edits and history. Mutating that object in place does not request a reload. To reset an editor, supply a newly created input object.
#A supplied store gives the application ownership
A supplied store exists independently of a mounted root. The application controls its lifetime and options. Multiple roots can borrow it and share model changes and history while keeping separate sessions.
Managed and controlled describe how a store accepts transactions. Root-owned value editing uses managed mode. A supplied store can also be managed; supplying it does not make edits host-controlled.
| Application need | Source choice |
|---|---|
| One editor, ordinary editing, Undo, or selection readouts | value |
| Read the current model or save accepted edits | value, with root context, a handle, or commit events |
| Replace a document from a file | A new value reference |
| Display several pages with one shared editing history | One supplied store borrowed by the roots |
| Create a binding or other controller before a root mounts | A supplied store owned alongside that controller |
| Accept or reject each transaction proposal | A supplied store in controlled mode |
| Register notation modules or configure custom store limits | A supplied store with explicit options |
Pages alone do not require a supplied store. A value-owned editor can contain several pages. Use a supplied store when application ownership or configuration requires one.
#Ownership includes cleanup
The managed helper, useDiagramStore() from @primeui/vue-diagram/composables, creates one store and owns its disposal in the component lifetime. It does not add controlled-mode options.
createDiagramStore() returns a result that the application validates and disposes. A root never disposes a supplied store. Dispose controllers before their store.
After a value reload, the effective store and session can change. Read the current context or root accessor again instead of keeping an old instance. SSR and lifecycle describes source transitions and teardown.
#Saving produces the portable model
Both source choices save the same complete version-1 model. The first save of short input includes default page and layer records, ownership IDs, model identity, rotation, and empty collections. Input, session state, and saved output are different objects.
Object input can omit schemaVersion and id. Saved JSON must explicitly declare version 1. Use serializeDiagramModel() to validate and expand input; JSON.stringify(shortInput) does not produce portable Diagram JSON. Existing codecs read the expanded output. Existing explicit documents retain their ownership and authored order.
DiagramModelInput, DiagramNodeInput, and DiagramConnectorInput describe construction. DiagramModel, store snapshots, context models, commit events, and transaction records remain complete. Short input does not weaken saved records or transaction validation.
#Pages and layers describe real structure
An omitted Root pageId selects the first page in authored order. That page stays selected while it exists, even after reordering. If it is deleted, the root selects the first remaining page. An explicit page ID must exist. A document with no remaining pages has no active canvas.
Multiple pages require explicit record page ownership. Multiple layers on a page require explicit record layer ownership. Root's displayed page does not determine a record's destination. Drawing can infer a sole layer on its current page; several layers require an explicit destination. Hidden and locked destinations still follow permission rules.