Skip to main content

​
Overview

The CanvasData interface represents the top-level structure of a canvas file in Obsidian. A canvas file is stored as JSON and contains collections of nodes and edges that make up the visual canvas.

​
Interface

export interface CanvasData {
    nodes: AllCanvasNodeData[];
    edges: CanvasEdgeData[];
    [key: string]: any;
}

​
Properties

​
nodes
AllCanvasNodeData[]
required
An array of all nodes in the canvas. Each node can be one of four types: file, text, link, or group.The AllCanvasNodeData type is a union of:
  • CanvasFileData - A node linking to a file in the vault
  • CanvasTextData - A node containing plaintext
  • CanvasLinkData - A node linking to an external resource
  • CanvasGroupData - A node representing a group container
​
edges
CanvasEdgeData[]
required
An array of all edges (connections) in the canvas. Edges connect nodes together to show relationships.See CanvasEdgeData for details on edge properties.
​
[key: string]
any
Supports arbitrary additional keys for forward compatibility. This allows canvas files to contain custom properties that may be used by future versions or plugins.

​
Example

{
  "nodes": [
    {
      "id": "node-1",
      "type": "file",
      "file": "Notes/MyNote.md",
      "x": 0,
      "y": 0,
      "width": 400,
      "height": 300
    },
    {
      "id": "node-2",
      "type": "text",
      "text": "This is a text node",
      "x": 500,
      "y": 0,
      "width": 300,
      "height": 200
    }
  ],
  "edges": [
    {
      "id": "edge-1",
      "fromNode": "node-1",
      "toNode": "node-2"
    }
  ]
}

​
Usage

When working with canvas files programmatically, you’ll typically:
  1. Read the canvas file as JSON
  2. Parse it into a CanvasData object
  3. Manipulate nodes and edges as needed
  4. Serialize back to JSON and save
// Reading a canvas file
const canvasFile = app.vault.getAbstractFileByPath('MyCanvas.canvas');
if (canvasFile instanceof TFile) {
    const content = await app.vault.read(canvasFile);
    const canvasData: CanvasData = JSON.parse(content);
    
    // Access nodes and edges
    console.log(`Canvas has ${canvasData.nodes.length} nodes`);
    console.log(`Canvas has ${canvasData.edges.length} edges`);
}
  • CanvasNodeData - Base interface for all node types
  • CanvasEdgeData - Interface for canvas edges
  • CanvasColor - Type for node and edge colors

Build docs developers (and LLMs) love

Get started for freeTalk to us