Diagram - Palette

#Usage

A palette inserts reusable symbols or saved graphs. Import its runtime parts from @primeui/vue-diagram/palette. The application owns the collection, registry and storage. This setup assumes the valid model/store from First Diagram.

import { shallowRef, onBeforeUnmount } from 'vue';
import { Diagram, DiagramSymbolRegistry } from '@primeui/vue-diagram';
import {
    DiagramPaletteRoot,
    DiagramPaletteTarget,
    DiagramPaletteSearch,
    DiagramPaletteGroups,
    DiagramPaletteStatus,
    DiagramPaletteCollection,
    createDiagramBasicLibrary,
    createDiagramLibraryPalette,
    registerDiagramPaletteSymbols,
    type DiagramPaletteTargetHandle
} from '@primeui/vue-diagram/palette';

const target = shallowRef<DiagramPaletteTargetHandle | null>(null);
const registry = new DiagramSymbolRegistry();
const collection = new DiagramPaletteCollection(createDiagramLibraryPalette([createDiagramBasicLibrary()]));
const release = registerDiagramPaletteSymbols(registry, collection.snapshot);
onBeforeUnmount(() => {
    release();
    collection.dispose();
    registry.dispose();
});

<Diagram.Root :store="store" page-id="page" :symbols="registry">
    <DiagramPaletteRoot v-if="target" :collection="collection" :registry="registry" :target="target">
        <DiagramPaletteSearch />
        <DiagramPaletteGroups />
        <DiagramPaletteStatus />
    </DiagramPaletteRoot>
    <DiagramPaletteTarget ref="target" layer-id="layer">
        <Diagram.Viewport label="Palette destination" style="height: 24rem" />
    </DiagramPaletteTarget>
</Diagram.Root>

The target must directly own the intended viewport. Palette and target share one Diagram root. Required layerId names an existing destination layer; optional parentId names a valid container. Keep registrations alive while inserted nodes need their drawings.

Initialize registry and collection with the library example below. Palette and destination must share this root, and layer layer must exist. Release symbol registrations and dispose owned resources on teardown.

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

#Insert a symbol

A working palette needs a collection, a symbol registry and an explicit target inside the same Diagram root. Register the definitions before offering their items for insertion. The target chooses the destination layer and optional parent.

Click an item or focus its button and press Enter or Space. Its top-left is placed at the visible canvas center. Drag an item onto the canvas to choose another location. Undo removes one insertion. Escape or a release outside the target cancels the preview without inserting a node.

Place this composition inside a root bound to the same registry through :symbols="registry". Required layerId identifies a destination on that root's page. Optional parentId inserts within a container. Read-only, locked destinations, creation constraints, containment and connection policies still apply. Pointer placement accounts for the target's pan, zoom and CSS scale.

#Search and categories

Build a catalog from the families your application needs. The flowchart and network factories below produce illustrative artwork and ports; they do not install executable notation semantics.

Search server or decision, choose a category, and expand/collapse a group. All query words match names, categories and keywords, ignoring case and combining accents. Search is limited to 256 characters. Results retain collection order and show at most 64 item buttons per page. These choices are local UI state, outside model history. Library factories supply artwork, not executable notation behavior.

Copied DiagramPaletteUI uses the same collection, registry and target. Its item slot receives item, scene, disabled, reason and insert; empty receives query and total. Do not nest interactive controls inside an item button.

Search for server or decision, then choose a category. Search matches all query words in names, categories and keywords, ignoring case and combining accents. Clear the query to return to the catalog. An empty result explains how to recover. Expand/collapse a category to manage the visible list.

Search, categories and expanded groups are local presentation state. They create no model history. Results retain stable input order and are paged at a maximum of 64 item buttons per page. This small catalog fits on one page; larger collections expose previous/next controls. Search input handling retains IME composition and limits queries to 256 characters.

#Customize items or the whole UI

Try the unavailable item, then Register missing symbol. The same item becomes available without changing its ID. In a child under DiagramPaletteRoot, call useDiagramPalette() from /palette. It returns DiagramPaletteControls, with readonly refs such as rows, groups, query, categoryChoices, pagination and placementState, plus actions including setQuery, setCategory, toggle and page. It does not change the portable DiagramPaletteModel data format.

For custom search/button markup use DiagramPaletteSearchInput.getInputProps and DiagramPaletteItemButton.getButtonProps through their scoped slots. Bind the returned props to native controls. Set itemId and unavailable on the item part; retain the reason in its accessible description. An unavailable item stays focusable so readers can discover why it cannot insert. DiagramPaletteStatus reports distinct current reasons and clears them when availability returns. Thumbnails render inert graphics rather than mounting application components.

The item's definition is initially missing, so its focusable button explains why it is unavailable. Choose Register missing symbol and insert the recovered item. Its saved palette reference does not need a new item ID.

State entries in this table are readonly refs: use .value in setup and destructure top-level refs for template unwrapping. Actions remain callable.

Thumbnails and drag previews render inert scene graphics. They do not instantiate application node components. The inserted node uses its normal content renderer.

#Capture a graph and save the palette

Capture a selection as a fragment item when several nodes and their connectors should be reused together. The capture includes selected nodes, descendants and internal connectors, with the definitions available in the supplied registry.

Select the original pair, capture it and insert the saved pair. Insertion remaps IDs and creates one Undo unit for the whole graph. Export JSON, edit it and import it again. Invalid input leaves the current collection available.

captureDiagramPaletteItem(store, session, registry, metadata) returns an item and its referenced definitions. Merge those into collection.replace(...). serializeDiagramPalette(collection.snapshot) emits version 1 JSON; parseDiagramPalette(text) validates imported data. Register imported definitions before replacing the collection and release that installation if replacement fails. Conflicting host definitions reject installation. Retain successful registration leases while inserted nodes depend on them.

Palette JSON contains inert data, not Vue templates or components. Unknown versions, duplicate identities and malformed graphs reject import. Limits include 512 items, 256 definitions, 64 nodes/128 connectors per graph and 8,000,000 text characters. Missing symbol references remain unavailable until the host supplies them. Storage, filenames and access control belong to the application.

Choose Select original pair, then Capture selection. Insert the saved pair and compare the node/connector counts. Each insertion remaps their identities and is one Undo action; Undo removes the new graph together.

Choose Export JSON, open Import or edit exported palette JSON, then choose Import JSON. To try recovery, edit the JSON to an invalid value and import it. The feedback reports rejection while the current palette remains available. Restore the exported JSON or use Reset to begin again.

captureDiagramPaletteItem(store, session, registry, metadata) returns the item and its referenced definitions. Choose a unique item id, name, description, category and keywords; merge the result into the collection with replace. A symbol item names symbolId and optional configuration/display dimensions. A fragment item stores a clipboard graph. Collection replacement validates the whole portable model before publishing it.

serializeDiagramPalette(collection.snapshot) produces version 1 JSON. parseDiagramPalette(text) validates imported text. Register the imported symbols before replacing the collection, and release that installation if replacement fails. Registry installation rejects definitions that conflict with existing host definitions. Keep successful registration leases while inserted nodes still need them; replacing the visible palette alone is not a reason to remove their drawings. The demo releases all leases on Reset or destruction.

#Cancellation and lifetime

Escape, an outside drop, stale geometry, item removal, registry changes, target replacement or destruction can cancel a placement preview. Completed managed insertions use the existing composite editing gateway. Approval or controlled proposals retain their own lifecycle; see Controlled State.

Reset remounts the owned root with a fresh store, clears history and restores the original palette and view. A saved palette is separate from the diagram containing its inserted nodes; export either one according to what the application needs to persist.

Escape, outside release, stale geometry, item removal, registry changes and target replacement can cancel previews. Cancellation after submitting a controlled proposal does not withdraw that proposal. Decide it explicitly at the store. Reset restores this example's owned resources and fixture; a saved palette and the diagram containing its inserted nodes are separate documents.

#Related Docs

• Symbols
• Content
• Architecture