PCUI Graph

After installation, import the Graph class along with the required PCUI and PCUI Graph styles. You can instantiate a graph by passing a schema object that defines nodes and edges.

Each node in the schema can have properties like name and fill. Edges define connections between nodes using from and to arrays (specifying node types or IDs) and can include styling like stroke. Once instantiated, append graph.dom to your document to render the graph view.

import Graph from '@playcanvas/pcui-graph';
import '@playcanvas/pcui/styles';
import '@playcanvas/pcui-graph/styles';

const schema = {
    nodes: {
        0: {
            name: 'Hello',
            fill: 'red'
        },
        1: {
            name: 'World',
            fill: 'green'
        }
    },
    edges: {
        0: {
            from: [0], // this edge can connect nodes of type 0
            to: [1], // to nodes of type 1
            stroke: 'blue'
        }
    }
};

const graph = new Graph(schema);
document.body.appendChild(graph.dom);

The Graph class is the primary entry point for creating node-based graphs. It extends the PCUI Element class. To instantiate a graph, you must provide a GraphSchema (defining the structure of nodes and edges) and an optional GraphOptions object.

GraphOptions Configuration

Example Usage

import Graph from '@playcanvas/pcui-graph';

const schema = {
    nodes: {
        'myNodeType': {
            attributes: [{ name: 'label', defaultValue: 'New Node' }]
        }
    },
    edges: {
        'myEdgeType': {
            from: ['myNodeType'],
            to: ['myNodeType']
        }
    }
};

const graph = new Graph(schema, {
    readOnly: false,
    edgeHoverEffect: true,
    initialData: {
        nodes: {
            'node1': { id: 'node1', nodeType: 'myNodeType', posX: 100, posY: 100, attributes: { label: 'First' } }
        },
        edges: {}
    }
});

document.body.appendChild(graph.dom);

The DEFAULT_CONFIG object provides the baseline configuration for the graph, including behavior flags and visual styling for nodes and edges. You can override these values when initializing your graph instance.

Behavior Flags

• readOnly: If true, prevents user interactions that modify the graph.
• passiveUIEvents: Controls how UI events are handled.
• incrementNodeNames: If true, automatically increments names when adding nodes.
• restrictTranslate: Restricts translation capabilities.
• edgeHoverEffect: Enables/disables visual feedback when hovering over edges.
• includeFonts: Whether to include custom fonts.
• useGlobalPCUI: Determines if the graph should use the global PCUI instance.
• adjustVertices: Controls vertex adjustment behavior.

Default Styles

The defaultStyles object defines the visual properties for the graph background, nodes, and edges. Key properties include:

Node Styles

• fill, fillSecondary, stroke, strokeSelected, strokeHover: Color properties for the node body and borders.
• textColor, textColorSecondary: Colors for text elements.
• baseHeight, baseWidth: Default dimensions for nodes.
• icon, iconColor: Icon configuration.

Edge Styles

• stroke, strokeSelected: Color of the edge line.
• strokeWidth, strokeWidthSelected: Thickness of the edge line.
• targetMarker: Boolean to show/hide markers at the edge end.
• connectionStyle: The visual style of the connection (e.g., 'default').

export const DEFAULT_CONFIG = {
    readOnly: false,
    passiveUIEvents: false,
    incrementNodeNames: false,
    restrictTranslate: false,
    edgeHoverEffect: true,
    includeFonts: true,
    useGlobalPCUI: false,
    adjustVertices: false,
    defaultStyles: {
        initialScale: 1,
        initialPosition: {
            x: 0,
            y: 0
        },
        background: {
            color: '#20292B',
            gridSize: 10
        },
        node: {
            fill: '#2c393c',
            fillSecondary: '#364346',
            stroke: '#293538',
            strokeSelected: '#F60',
            strokeHover: 'rgba(255, 102, 0, 0.32)',
            textColor: '#FFFFFF',
            textColorSecondary: '#b1b8ba',
            includeIcon: true,
            icon: '',
            iconColor: '#F60',
            baseHeight: 28,
            baseWidth: 226,
            textAlignMiddle: false,
            lineHeight: 12
        },
        edge: {
            stroke: 'rgb(3, 121, 238)',
            strokeSelected: '#F60',
            strokeWidth: 2,
            strokeWidthSelected: 2,
            targetMarker: true,
            connectionStyle: 'default'
        }
    }
};

Use GraphView to programmatically add, remove, and update nodes within the graph. When adding a node, you must provide data, a schema, and callbacks for edge creation and node selection.

To optimize performance when adding multiple nodes at once, use batchCells() before adding nodes and applyBatchedCells() once finished. This prevents unnecessary re-renders.

Common node operations include:

• addNode(...): Creates a new node.
• removeNode(modelId): Removes a node by its model ID.
• updateNodeAttribute(id, attribute, value): Updates a specific attribute on a node.
• setNodeAttributeErrorState(id, attribute, value): Sets the error state for a node attribute.
• updateNodePosition(id, pos): Moves a node to a new { x, y } position.
• updateNodeType(id, nodeType): Changes the type of a node.
• selectNode(id) / deselectNode(id): Controls the selection state of a node.

// Adding a node with batching for performance
graphView.batchCells();

graphView.addNode(
    { id: 'node-1', type: 'default' }, // NodeData
    nodeSchema,                        // NodeSchema
    (edgeId, edgeData) => {           // onCreateEdge callback
        console.log('Edge created:', edgeId);
    },
    (nodeData) => {                   // onNodeSelected callback
        console.log('Node selected:', nodeData.id);
    }
);

graphView.applyBatchedCells();

The Graph class uses DOM-based events to communicate changes. You can listen to these events using the .on() method. Note that if readOnly is enabled, most interaction events are suppressed.

Available Graph Actions (Events)

Events are dispatched using the GRAPH_ACTIONS constants. Common events include:

• ADD_NODE: Fired when a node is added.
• DELETE_NODE: Fired when a node is deleted.
• SELECT_NODE: Fired when a node is selected.
• UPDATE_NODE_POSITION: Fired when a node is moved.
• UPDATE_NODE_ATTRIBUTE: Fired when a node attribute changes.
• ADD_EDGE: Fired when an edge is created.
• DELETE_EDGE: Fired when an edge is removed.
• SELECT_EDGE: Fired when an edge is selected.
• DESELECT_ITEM: Fired when selection is cleared.

Example: Listening for Node Selection

graph.on('EVENT_SELECT_NODE', ({ node, prevItem }) => {
    console.log('Selected node:', node.id);
    console.log('Previous item:', prevItem);
});