Getting Started

Overview

The Vertical Tabs API allows other Obsidian plugins to interact with and customize tabs and groups programmatically. You can set custom icons, colors, and titles for tabs and groups, listen to workspace events, and add custom menu items to context menus.

Notice

The Vertical Tabs API is currently in beta and requires a subscription to the Beta Program.

Plugin developers: If you want to use the API and integrate your plugin with Vertical Tabs, please complete this form to request free access.

Users: If you want to try out the API features, please subscribe to the Beta Program. All users will receive a free update at a later date. For more information, please refer to the Beta Program documentation and the Roadmap.

Installation

Install the API types in your plugin project:

npm install obsidian-vertical-tabs-api

Basic usage

Access the API through the Vertical Tabs plugin instance:

import { Plugin } from "obsidian";
import { VerticalTabsAPI } from "obsidian-vertical-tabs-api";
 
export default class MyPlugin extends Plugin {
  async onload() {
    // Get the Vertical Tabs plugin
    const vtPlugin = this.app.plugins.getPlugin("vertical-tabs");
    
    if (!vtPlugin?.api) {
      console.warn("Vertical Tabs not available");
      return;
    }
 
    const api: VerticalTabsAPI = vtPlugin.api;
    
    // Use the API
    const version = api.getVersion();
    console.log("Vertical Tabs API version:", version);
  }
}

Checking availability

The Vertical Tabs plugin can be loaded and unloaded at any time. Always access the API safely to ensure your integration is robust.

For a complete guide on safe API access patterns, see Safe API Access.

Quick check:

export default class MyPlugin extends Plugin {
  async onload() {
    // Listen for Vertical Tabs load
    this.registerEvent(
      this.app.workspace.on("vertical-tabs:load", () => {
        const vtPlugin = this.app.plugins.getPlugin("vertical-tabs");
        if (vtPlugin?.api) {
          // Initialize your integration
        }
      })
    );
 
    // Check if already loaded
    const vtPlugin = this.app.plugins.getPlugin("vertical-tabs");
    if (vtPlugin?.api) {
      // Initialize your integration
    }
  }
}

Next steps

• Safe API Access - Learn robust patterns for accessing the API
• Customization - Learn how to customize tabs and groups
• Events - Subscribe to workspace events
• Menus - Add custom menu items
• Utilities - Utility methods for working with tabs and groups