Skip to main content

​
Overview

Canvas nodes are the building blocks of an Obsidian canvas. There are four types of nodes: file nodes, text nodes, link nodes, and group nodes. All node types share common positional properties defined in the base CanvasNodeData interface.

​
Base Interface

export interface CanvasNodeData {
    id: string;
    x: number;
    y: number;
    width: number;
    height: number;
    color?: CanvasColor;
    [key: string]: any;
}

​
Base Properties

​
id
string
required
The unique identifier for this node. Must be unique within the canvas.
​
x
number
required
The horizontal position of the node’s top-left corner in canvas coordinates.
​
y
number
required
The vertical position of the node’s top-left corner in canvas coordinates.
​
width
number
required
The width of the node in pixels.
​
height
number
required
The height of the node in pixels.
​
color
CanvasColor
The color of this node. Can be a number (like "1") representing one of the currently 6 supported colors, or a custom color using the hex format "#FFFFFF".
​
[key: string]
any
Supports arbitrary additional keys for forward compatibility.

​
Node Types

​
CanvasFileData

A node that links to a file located somewhere in the vault. 
export interface CanvasFileData extends CanvasNodeData {
    type: 'file';
    file: string;
    subpath?: string;
}
​
type
'file'
required
Must be "file" for file nodes.
​
file
string
required
The path to the file in the vault, relative to the vault root.Example: "Notes/MyNote.md"
​
subpath
string
An optional subpath which links to a heading or a block within the file. Always starts with #.Examples:
  • "#Heading" - Links to a heading
  • "#^blockid" - Links to a specific block

​
CanvasTextData

A node that contains plaintext content. 
export interface CanvasTextData extends CanvasNodeData {
    type: 'text';
    text: string;
}
​
type
'text'
required
Must be "text" for text nodes.
​
text
string
required
The text content of the node. Can include Markdown formatting.

​
CanvasLinkData

A node that links to an external resource (URL). 
export interface CanvasLinkData extends CanvasNodeData {
    type: 'link';
    url: string;
}
​
type
'link'
required
Must be "link" for link nodes.
​
url
string
required
The URL to the external resource.Example: "https://obsidian.md"

​
CanvasGroupData

A node that represents a container group for organizing other nodes. 
export interface CanvasGroupData extends CanvasNodeData {
    type: 'group';
    label?: string;
    background?: string;
    backgroundStyle?: BackgroundStyle;
}
​
type
'group'
required
Must be "group" for group nodes.
​
label
string
Optional label to display on top of the group.
​
background
string
Optional background image. Stores the path to the image file in the vault.Example: "Images/background.png"
​
backgroundStyle
BackgroundStyle
Optional background image rendering style. Defaults to "cover".Possible values:
  • "cover" - Scale the image to cover the entire group
  • "ratio" - Maintain aspect ratio
  • "repeat" - Tile the image

​
Examples

​
File Node

{
  "id": "abc123",
  "type": "file",
  "file": "Documents/Project Plan.md",
  "subpath": "#Phase 1",
  "x": 100,
  "y": 200,
  "width": 400,
  "height": 300,
  "color": "1"
}

​
Text Node

{
  "id": "def456",
  "type": "text",
  "text": "# Important Note\n\nThis is some **markdown** content.",
  "x": 600,
  "y": 200,
  "width": 300,
  "height": 200,
  "color": "#FF6B6B"
}

{
  "id": "ghi789",
  "type": "link",
  "url": "https://obsidian.md/plugins",
  "x": 1000,
  "y": 200,
  "width": 350,
  "height": 250
}

​
Group Node

{
  "id": "jkl012",
  "type": "group",
  "label": "Research Materials",
  "background": "Assets/pattern.png",
  "backgroundStyle": "repeat",
  "x": 0,
  "y": 0,
  "width": 1200,
  "height": 800,
  "color": "3"
}

​
Type Union

The AllCanvasNodeData type is a union of all node types: 
export type AllCanvasNodeData = 
    | CanvasFileData 
    | CanvasTextData 
    | CanvasLinkData 
    | CanvasGroupData;
This allows you to work with any node type while maintaining type safety when checking the type property.

​
Usage Example

function processNode(node: AllCanvasNodeData) {
    // Common properties available on all nodes
    console.log(`Node ${node.id} at (${node.x}, ${node.y})`);
    
    // Type-specific handling
    switch (node.type) {
        case 'file':
            console.log(`File: ${node.file}`);
            if (node.subpath) {
                console.log(`Subpath: ${node.subpath}`);
            }
            break;
        case 'text':
            console.log(`Text: ${node.text}`);
            break;
        case 'link':
            console.log(`URL: ${node.url}`);
            break;
        case 'group':
            console.log(`Group: ${node.label || 'Unlabeled'}`);
            break;
    }
}
  • CanvasData - The top-level canvas file structure
  • CanvasEdgeData - Interface for connections between nodes
  • CanvasColor - Type for color encoding
  • BackgroundStyle - Type for group background rendering

Build docs developers (and LLMs) love

Get started for freeTalk to us