Canvas Folding

Canvas Folding adds hierarchical folding, level views, and branch focus to the standard Obsidian Canvas. Its own branch, group, and focus states remain outside the .canvas file.

Requires Obsidian 1.13.0 or later. Canvas Folding works on desktop and mobile and has no dependency on Advanced Canvas.

Tested platforms

The current plugin has been manually tested on:

• Windows 11;
• macOS;
• iPadOS;
• iOS.

The compact node-control geometry and its neutral highlight states were also verified with Obsidian's default theme, Minimal 9.0.2, and AnuPpuccin 1.5.0 on macOS, iPadOS, and iOS. The AnuPpuccin pass used Style Settings 1.0.9 with the maintained test profile.

If Canvas Folding is useful to you, you can support its continued development by buying me a coffee.

Features

• Collapse or expand one or more selected branches recursively in one action.
• Collapse every rooted branch while keeping roots and isolated nodes visible.
• Collapse or expand every Canvas group by geometric containment, including empty and nested groups.
• Show the complete Canvas through a chosen global level.
• Show one node, a limited number of levels, or an entire branch from a node control.
• Focus any node, group, or complete branch while dimming and protecting the remaining Canvas context.
• Use folding controls with hidden-item counts on parent nodes and focus controls on visible, expanded nodes and groups, including leaves.
• Show or hide folding and focus controls independently without changing the current view state.
• Use a movable, responsive Canvas Folding toolbar.
• Keep state separately for each open Canvas tab.
• Optionally restore states between sessions without modifying Canvas files.
• React to node and edge changes, undo/redo, duplication, and Canvas re-renders.
• Handle multiple roots, multiple parents, shared descendants, cross-links, cycles, groups, text, file, image, and link nodes.
• Expose an optional versioned API for other plugins.

Tested alongside Advanced Canvas

Canvas Folding does not require Advanced Canvas, but both plugins can remain enabled and work alongside each other. Canvas Folding 1.0.0 completed an extensive coexistence matrix with Advanced Canvas 6.5.4 and Obsidian 1.13.7 on macOS, iPadOS, and iOS.

The tests covered plugin load order and restarts, node and edge editing, different node types and shapes, nested groups, shared descendants, cycles, focus, levels, persistence, multiple Canvas tabs, undo/redo, and desktop and touch interaction. No unintended mutual interference was found in the supported standard Canvas features: each plugin retains its own controls and state, and using one plugin does not silently change the state owned by the other. See Using Canvas Folding with Advanced Canvas for the few details worth knowing when both plugins hide content.

Before the 1.1.0 release, the changed controls, connected groups, branch focus, shared-parent behavior, editing, undo/redo, and plugin lifecycle also passed a focused regression test with Advanced Canvas 7.0.0 on macOS.

Visual guide

Collapse and expand branches

Each eligible node shows its compact controls inside the upper-right corner, beyond the native resize border. The − control collapses the complete directed branch. Its replacement shows the total number of hidden nodes and groups, so folded state stays readable across the Canvas. The control grows leftward for two- or three-digit counts.

Use the control tooltips

On desktop, pause the pointer over a folding control. Its tooltip states whether the click will collapse or expand the branch, breaks the hidden total down into nodes and groups, and points to the branch display menu.

The tooltip is especially useful with Advanced Canvas: if an Advanced Canvas group currently hides descendants, it says how many are hidden there and explains that Canvas Folding preserves the group's own collapsed state.

On touch devices, where hover is unavailable, long-press the control; an Advanced Canvas notice with the hidden-descendant count appears at the top of the branch display menu.

Choose visible branch levels

Right-click or long-press a node control to show only the parent, reveal a specific number of descendant levels, or show the entire branch.

Focus a branch

Focus mode keeps the selected branch fully active while dimming and protecting the surrounding Canvas. The wider context remains visible without distracting from the branch being worked on.

Use the focus symbol on any node or group to enter focus directly. Items without children receive the same control, so they can be focused individually. Click the active focus control again, or use the toolbar focus action, to exit. Focusing a group keeps the group and every item geometrically contained by it fully active while unrelated Canvas content is dimmed.

Quick start

1. Install Canvas Folding, enable it, and open a Canvas.
2. Use directed edges from parent to child to define the hierarchy.
3. Click or tap a parent's − control, or select the parent and use the Canvas Folding toolbar. Right-click or long-press the control to choose a visible branch level.
4. Optionally enable Remember canvas states between sessions to restore folding states after closing a tab or restarting Obsidian.

How folding works

Canvas Folding interprets directed Canvas edges as hierarchy: fromNode → toNode. A node can therefore have multiple parents, and the Canvas is treated as a general directed graph rather than as a strict tree. Traversal is deterministic and cycle-safe.

Global Canvas levels are measured from root nodes, meaning nodes without an incoming edge. Level 0 contains the roots, level 1 their direct children, and each following level the next generation of directed descendants. If a node is reachable through multiple roots or paths, its shortest directed distance from any root determines its level. A Canvas without a root has no global level view, but its individual branch controls remain available.

Parent nodes receive a directly visible branch-folding control inside their upper-right corner. When descendants are hidden, it displays the total number of hidden nodes and groups. The tooltip reports both categories separately:

• Click or tap the control to collapse or expand the complete branch.
• On desktop, hover over it to read its action, descendant count, and any additional Advanced Canvas collapsed-group information.
• Open its context menu to show only the node, show through a selected level, or show the entire branch.
• Shared descendants stay visible automatically while another open parent branch still reaches them. Folding hides only exclusive descendants and the connections belonging to the collapsed branch.

Every group also receives its own −/+ control in a square, group-colored frame matching the group-name height directly to the right of its name. Collapsing it hides every fully contained node and nested group together with all incident edges and edge labels. Empty groups can be collapsed too. Group-folding and directed branch-folding states stay independent; Expand all branches clears both.

Every visible, expanded node and group also receives a focus control. A collapsed parent or group shows only its applicable folding controls; its focus control returns when it is expanded, provided focus controls are enabled. Folding controls and focus controls can be hidden independently through the toolbar or command palette. Hiding either kind of control changes only the interface: it does not expand branches or end an active focus. On touch devices, the same compact controls remain directly available without selection; the Canvas toolbar provides an additional route for selected-branch actions. Controls occupy only the upper-right interior, leaving the complete node border available for native resizing. Folded branches keep their count or + indicator visible across the Canvas. When a group is focused, its geometrically contained items belong to the focus area even when they have no directed edge from that group.

When the Advanced Canvas plugin is active, its familiar group switches stay to the left of the group names. Canvas Folding does not show its new right-hand group switches and internally disables its own group-folding mechanism. It does not duplicate or override Advanced Canvas controls. Branch folding and focus remain independent and continue to be available where their nodes are visible.

Hidden nodes also hide every incident edge, including edge labels. A collapsed branch connection can remain hidden while its shared endpoint stays visible through another open parent. An unconnected non-empty Canvas group is hidden when all non-group nodes geometrically contained by it are hidden. A group connected through directed edges follows its own branch instead: hiding a separate branch inside it does not hide the group frame. Empty groups remain visible unless the group itself is a directed descendant of a folded parent. When a group is hidden as such a descendant, every node geometrically contained by it is hidden as well, even without a separate parent edge. If this makes every descendant of another visible node unavailable, that node's folding control stays in place but is disabled with the explanation Branch hidden by folded group. Its existing branch state is preserved and the control becomes active again when the group branch is expanded.

Canvas toolbar

The optional toolbar provides the main Canvas Folding actions directly in the Canvas. Drag its handle to move it, or focus the handle and use the arrow keys. On narrow views and mobile devices, the toolbar can be scrolled horizontally.

The toolbar includes actions for:

• one or more selected branches: collapse and expand every applicable branch;
• the whole Canvas: collapse all rooted branches, select a global visible level, and expand all branches;
• showing or hiding folding controls;
• showing or hiding focus controls, followed by entering or exiting focus;
• inspecting the graph;
• showing the current state;
• hiding the toolbar itself.

Unavailable actions are disabled. The toolbar can always be shown, hidden, toggled, or reset through the command palette.

Commands

All commands are available from the command palette when their Canvas context is valid:

Keyboard and touch

Node controls follow a depth-first Tab order. On a node, its focus control comes before its folding control. Upper child branches are visited completely before lower sibling branches. If exactly one node is selected, navigation starts at that node's first available control.

• Enter or Space activates a node control or toolbar action.
• The keyboard context-menu key opens the branch-level menu from a folding control.
• Arrow keys move the focused toolbar handle.
• Keyboard focus remains on the invoked control after an action.

Node controls keep their compact desktop size on coarse-pointer devices so they cover less card content; Canvas zoom remains available for closer touch interaction. The toolbar supports horizontal touch scrolling and dragging. Canvas node selection remains native on iPhone and iPad. Long-press access to the branch-level menu depends on whether the installed Obsidian/WebView version emits a context-menu event.

State and persistence

By default, fold state, level restrictions, temporary branch-display exceptions, and branch focus are remembered only in the open Canvas tab. Navigating to another file and back in that tab restores its state; closing the tab discards it.

Enable Remember canvas states between sessions to also restore state in new tabs and after restarting Obsidian or the plugin. The data is stored in Canvas Folding's local data.json, never in the .canvas file. Entries for deleted or renamed Canvas files follow actual Vault events, and stale node IDs are cleaned after actual Canvas modifications. Temporary runtime unavailability during plugin startup or updates and opening the state manager never remove saved states. Every entry can be reviewed or removed explicitly from the settings.

Turning persistence off does not delete existing saved states. Changes made while it is off remain limited to the current tab. Turning persistence on again discards those temporary changes and restores the previously saved states. Canvases without an existing saved state return to their default expanded state.

Canvas Folding does not synchronize settings or persisted states between devices. They belong to the local Obsidian plugin configuration, so the same Canvas can intentionally have different folding states on a Mac, iPhone, and iPad. If Obsidian Sync or another synchronization system is configured to sync plugin settings and data, it may also transfer Canvas Folding's data.json; that behavior is controlled by the synchronization setup, not by Canvas Folding.

If an older Canvas Folding version encounters plugin data written by a newer schema version, it preserves that data and shows a notice instead of overwriting unknown fields. Existing settings and saved states remain read-only, while folding continues to work temporarily in open tabs. Reinstall the newer plugin version to resume persistence.

Installation

Install Canvas Folding directly from Settings → Community plugins → Browse in Obsidian.

For a manual installation, download main.js, manifest.json, and styles.css from a GitHub release and place them in:

<vault>/.obsidian/plugins/canvas-folding/

Then reload Obsidian and enable Canvas Folding under Community plugins.

Demo Canvas

The repository includes a documented demo covering a basic tree, a shared descendant, a cycle, an isolated node, groups, and different node types: examples/Canvas Folding Demo/.

Copy the complete Canvas Folding Demo folder to the root of a vault and open Canvas Folding Demo/Canvas Folding Demo.canvas. The explanatory cards on the Canvas suggest actions and describe the expected result.

Focused regression fixtures and the full manual V1 test matrix remain separately available under manual-tests/.

Settings

The settings page starts with a reminder that Canvas Folding stores its own folding state outside Canvas files. It also explains the one-time normalization that can be needed when control returns from a collapsed Advanced Canvas group.

• Show canvas toolbar initially controls the toolbar's state when the plugin loads. Commands can change it at any time.
• Show branch controls initially controls node buttons when the plugin loads. Commands can change them at any time.
• Show focus controls initially controls the focus symbols on all visible nodes and groups. Commands can change them at any time.
• Background opacity during branch focus controls how strongly unrelated Canvas content is dimmed.
• Remember canvas states between sessions enables persistent state.
• Show status notices enables action confirmations.
• Manage persisted canvas states lists the Canvas name, full path and remove action for every cross-session state. Click Canvas or Path to sort in either direction. Longer lists scroll vertically while the column header and Remove all action remain available. Opening the manager is read-only; entries change only after an actual Vault event or an explicit Remove or Remove all action. Currently open tabs keep their session state.
• Debug logging writes diagnostic details to the developer console.

Update Description

After an update with new user-facing features, Canvas Folding opens a Markdown-rendered What's new view once. Closing it removes the view completely; no release-note file is created in the Vault and it does not reopen on every Obsidian start.

Use Show last update at the bottom of the plugin settings to open the description again at any time. Use Show readme beside it to open this complete documentation locally inside Obsidian. The repository keeps the same text in Last Update.md.

Privacy and data handling

Canvas Folding works entirely locally and sends no Canvas or vault data to external services. The Ko-fi image in this README is documentation content and is not loaded or contacted by the installed plugin.

When persistence is enabled, local plugin data contains vault-relative Canvas paths, node IDs, and visibility settings. Canvas Folding does not write its own folding state or layout into Canvas files. If Advanced Canvas is disabled while one of its groups is collapsed, Canvas Folding may normalize that external collapsed representation once so the original nodes and edges remain available.

Compatibility and limitations

• Obsidian Canvas currently exposes only some extension points through public TypeScript APIs. Private runtime access is isolated in a compatibility layer and guarded defensively.
• Advanced Canvas portals and presentations are not part of this compatibility guarantee because those experimental features currently have upstream limitations of their own.
• Long-press context menus depend on the mobile platform and WebView behavior.
• Canvas Folding does not perform automatic layout, graph navigation, or branch styling.

Using Canvas Folding with Advanced Canvas

Canvas Folding keeps directed branch folds and its own group folds only in the current view or, optionally, in Canvas Folding's data.json. Advanced Canvas' collapsible groups have their own controls, history, copy behavior and drag preview, and store their group state in the Canvas data. When that Advanced Canvas control is present, Canvas Folding defers group folding for the affected group to Advanced Canvas instead of showing a duplicate switch.

When both mechanisms are used, check which control owns the hidden content:

• A numbered Canvas Folding control means that Folding currently hides that many nodes and groups below the branch. Its tooltip separates both counts.
• A Canvas Folding group −/+ appears only when no external group control is already responsible for that group.
• A Canvas Folding − can remain visible while an Advanced Canvas group hides descendants inside it; the control's tooltip explains this case.
• On touch devices, long-press that control to see an Advanced Canvas notice with the hidden-descendant count at the top of the branch display menu.
• Expanding one mechanism does not automatically expand the other.

Enabling or disabling Advanced Canvas is handled in the open Canvas. Canvas Folding removes duplicate controls, restores complete group content when control returns from a collapsed Advanced Canvas group, and recalculates its compact edge geometry. This hand-off requires substantial internal coordination because both plugins use different group-state and rendering models, but it introduces no dependency between them.

Public API

Other plugins can optionally discover Canvas Folding by the stable plugin ID canvas-folding. The read-only CanvasFoldingApi v1 returns effective hidden node and edge IDs for a vault-relative Canvas path. It exposes no DOM elements, Canvas views, workspace leaves, or internal state classes.

See docs/api.md for the complete contract and a defensive discovery example. Consumers must remain functional when Canvas Folding is not installed, disabled, or exposes an incompatible API version.

Development

Requires Node.js 20.19 or later.

npm ci
npm test
npm run build:prod

For a local runtime test, explicitly set OBSIDIAN_PLUGINS_DIR to the target vault's .obsidian/plugins directory:

OBSIDIAN_PLUGINS_DIR="/path/to/TestVault/.obsidian/plugins" npm run deploy:test-vault

The production release contains main.js, manifest.json, and styles.css. See CONTRIBUTING.md and docs/release-checklist.md for development and release checks.

Support and feedback

Please report reproducible problems and feature requests through the GitHub issue tracker.

License

Canvas Folding is licensed under the GNU General Public License v3.0 or later.