Skip to main content

sidebarAPI

MS Code Extension API

MS Code Extension API / core/extensionAPI/modules/window/sidebarAPI

core/extensionAPI/modules/window/sidebarAPI

Functions​

createSidebarAPI()​

createSidebarAPI(): object

Defined in: core/extensionAPI/modules/window/sidebarAPI.ts:12

Returns​

sidebar: object

mscode.window.sidebar​

Full control over the IDE sidebar — layout state, panel focus, custom section registration, dynamic action injection, and event tracking.

Architecture overview​

ActivityBar icon (id: 'files')
└── SidebarPanel  (registered via sidebar.registerPanel)
├── Header  (title + actions[])
├── Section  (collapsible, registered via sidebar.addSection)
│     ├── content: React component / JSX / render-prop
│     └── actions: MenuItem[]  ← same shape as ContextMenu
└── Section  ...

Action system & Auto-Hoisting​

actions use the exact same MenuItem[] shape as openMenu() / ContextMenu. Advanced features include:

  • order: Automatically sorts actions before rendering.
  • flat: Unpacks structural containers directly into the root level.
  • Auto-Hoist: If a submenu (children) has exactly 1 item, it is flattened automatically unless flat: false is set.

Actions beyond maxOverflow (default 3) automatically collapse into a ⋮ menu. Any module can inject extra actions via sidebar.addAction(targetMenuId, item).

Every action group has a stable string ID:

header  → "sidebar/<activityBarId>/header/actions"
section → "sidebar/<activityBarId>/<sectionId>/actions"

Use sidebar.menuId helpers to compute these safely.

sidebar.addAction​

addAction: (targetMenuId, action) => object

Inject a single action into an existing section's action bar — or the panel header.

The action appears at the end of the current list. If the total exceeds maxOverflow, it automatically moves into the ⋮ overflow context menu.

Returns a dispose() to remove the injected action cleanly.

Parameters​
targetMenuId​

string

Use sidebar.menuId.* helpers to get the right ID.

action​

MenuItem

A MenuItem — same shape as openMenu() items.

Returns​

object

dispose​

dispose: () => void

Returns​

void

Example​
// Add "Git Blame" to the file-tree section actions from a Git extension
const { dispose } = mscode.window.sidebar.addAction(
  mscode.window.sidebar.menuId.section('files', 'file-tree'),
  {
    id:      'git-blame',
    icon:    'git-branch',
    label:   'Toggle Git Blame',
    onClick: () => commands.executeCommand('git.blame.toggle'),
  },
);

// Add a submenu to the Explorer header
mscode.window.sidebar.addAction(
  mscode.window.sidebar.menuId.header('files'),
  {
    id:    'run-scripts',
    icon:  'play',
    label: 'Run Script',
    children: [
      { id: 'build', label: 'Build',  onClick: () => runScript('build') },
      { id: 'test',  label: 'Test',   onClick: () => runScript('test')  },
      { id: 'sep',   type: 'separator' },
      { id: 'clean', label: 'Clean',  onClick: () => runScript('clean') },
    ],
  },
);
sidebar.addSection​

addSection: (activityBarId, sectionDef) => object

Dynamically inject a collapsible section into an existing panel.

If the target panel doesn't exist yet, a header-less panel is created automatically so the section still appears when the panel opens.

Returns a dispose() that removes the section cleanly.

Parameters​
activityBarId​

string

Target panel id (e.g. 'files', 'git')

sectionDef​

SidebarSectionDef

Section configuration

Returns​

object

dispose​

dispose: () => void

Returns​

void

Example​
// Add an "NPM Scripts" section to the Explorer panel
const { dispose } = mscode.window.sidebar.addSection('files', {
  id:              'npm-scripts',
  title:           'NPM Scripts',
  content:         NpmScriptsComponent,
  defaultExpanded: false,
  defaultHeight:   200,
  actions: [
    { id: 'run-all', icon: 'play', label: 'Run All', onClick: runAll },
  ],
});

// Add a static block (no collapsible chrome) by passing title: ''
mscode.window.sidebar.addSection('search', {
  id:      'search-controls',
  title:   '',          // ← empty title = static block
  content: SearchControlsComponent,
});
sidebar.focusPanel​

focusPanel: (panelId) => void

Focus a specific panel — opens the sidebar if it was hidden. Equivalent to the user clicking the ActivityBar icon.

Parameters​
panelId​

string

Returns​

void

Example​
// Jump to Source Control from a command
mscode.window.sidebar.focusPanel('git');

// Open a custom extension panel
mscode.window.sidebar.focusPanel('database-explorer');
sidebar.menuId​

menuId: object = sidebarMenuId

Helpers to compute stable action group Menu IDs without magic strings.

Example​
mscode.window.sidebar.menuId.header('files')
// → "sidebar/files/header/actions"

mscode.window.sidebar.menuId.section('files', 'file-tree')
// → "sidebar/files/file-tree/actions"
sidebar.menuId.header​

header: (activityBarId) => string

Parameters​
activityBarId​

string

Returns​

string

sidebar.menuId.section​

section: (activityBarId, sectionId) => string

Parameters​
activityBarId​

string

sectionId​

string

Returns​

string

sidebar.onDidChangeActivePanel​

onDidChangeActivePanel: (handler) => object

Fires whenever the user switches to a different panel.

Parameters​
handler​

(panelId) => void

Returns​

object

dispose​

dispose: () => void

Returns​

void

Example​
mscode.window.sidebar.onDidChangeActivePanel(panelId => {
  if (panelId === 'git') refreshGitStatus();
});
sidebar.onDidChangeState​

onDidChangeState: (handler) => object

Fires whenever the sidebar layout state changes ('expanded' ↔ 'collapsed' ↔ 'hidden').

Parameters​
handler​

(state) => void

Returns​

object

dispose​

dispose: () => void

Returns​

void

Example​
const sub = mscode.window.sidebar.onDidChangeState(state => {
  if (state === 'hidden') pauseExpensiveUpdates();
  else                    resumeUpdates();
});

// Unsubscribe when the extension deactivates:
context.subscriptions.push(sub);
sidebar.onDidChangeWidth​

onDidChangeWidth: (handler) => object

Fires when the user drags the sidebar resize handle.

Parameters​
handler​

(width) => void

Returns​

object

dispose​

dispose: () => void

Returns​

void

Example​
mscode.window.sidebar.onDidChangeWidth(px => {
  console.log(`Sidebar is now ${px}px wide`);
});
sidebar.registerPanel​

registerPanel: (panelDef) => object

Register a complete sidebar panel tied to an ActivityBar icon.

If a panel with the same activityBarId already exists it is replaced. Returns a dispose() to unregister cleanly on extension deactivation.

Parameters​
panelDef​

SidebarPanelDef

Returns​

object

dispose​

dispose: () => void

Returns​

void

Example​
const dispose = mscode.window.sidebar.registerPanel({
  activityBarId: 'database-explorer',
  header: {
    title: 'Database',
    maxOverflow: 2,
    actions: [
      { id: 'connect', icon: 'plug',     label: 'Connect',    onClick: connect },
      { id: 'refresh', icon: 'refresh',  label: 'Refresh',    onClick: refresh },
      // ↓ overflows into ⋮ because maxOverflow is 2
      { id: 'settings',icon: 'settings', label: 'DB Settings',onClick: openSettings },
    ],
  },
  sections: [
    {
      id:          'tables',
      title:       'Tables',
      content:     TablesComponent,
      fillHeight:  true,
      actions: [
        { id: 'new-table', icon: 'add', label: 'New Table', onClick: newTable },
      ],
    },
  ],
});

// Clean up when the extension is deactivated:
context.subscriptions.push({ dispose });
sidebar.removeAction​

removeAction: (targetMenuId, actionId) => void

Remove a previously injected action by its id.

Parameters​
targetMenuId​

string

actionId​

string

Returns​

void

Example​
mscode.window.sidebar.removeAction(
  mscode.window.sidebar.menuId.section('files', 'file-tree'),
  'git-blame',
);
sidebar.removeSection​

removeSection: (activityBarId, sectionId) => void

Remove a section from a panel.

Parameters​
activityBarId​

string

sectionId​

string

Returns​

void

Example​
mscode.window.sidebar.removeSection('files', 'npm-scripts');
sidebar.setSectionVisibility​

setSectionVisibility: (activityBarId, sectionId, visible) => void

Show or hide a section without removing it from the registry. The section resumes from its last state when made visible again.

Parameters​
activityBarId​

string

sectionId​

string

visible​

boolean

Returns​

void

Example​
// Hide Timeline from Explorer
mscode.window.sidebar.setSectionVisibility('files', 'timeline', false);

// Restore it
mscode.window.sidebar.setSectionVisibility('files', 'timeline', true);
sidebar.setState​

setState: (newState) => void

Programmatically set the sidebar layout state.

Parameters​
newState​

SidebarState

Returns​

void

Example​
mscode.window.sidebar.setState('hidden');    // collapse entirely
mscode.window.sidebar.setState('expanded');  // open fully
mscode.window.sidebar.setState('collapsed'); // show only icons
sidebar.updateSection​

updateSection: (activityBarId, sectionId, patch) => void

Patch any properties of an existing section without replacing it entirely.

Common uses: swap the content component, change title, update actions.

Parameters​
activityBarId​

string

sectionId​

string

patch​

Partial<SidebarSectionDef>

Returns​

void

Example​
// Swap content when the user changes a setting
mscode.window.sidebar.updateSection('files', 'file-tree', {
  title: 'Workspace — readonly mode',
});

// Update actions list
mscode.window.sidebar.updateSection('files', 'symbols', {
  actions: [
    { id: 'sort-name', icon: 'sort-precedence', label: 'Sort by Name', onClick: sortByName },
    { id: 'sep',       type: 'separator' },   // ← inline | separator
    {
      id:       'filter',
      icon:     'filter',
      label:    'Filter',
      // Submenu — opens nested context menu on click
      children: [
        { id: 'show-vars',     label: 'Variables',  onClick: () => {} },
        { id: 'show-funcs',    label: 'Functions',  onClick: () => {} },
        { id: 'show-classes',  label: 'Classes',    onClick: () => {} },
      ],
    },
  ],
});
sidebar.activePanel​
Get Signature​

get activePanel(): string

Defined in: core/extensionAPI/modules/window/sidebarAPI.ts:310

The id of the currently active panel (e.g. 'files', 'git', 'search').

Example​
if (mscode.window.sidebar.activePanel === 'git') { ... }
Returns​

string

sidebar.state​
Get Signature​

get state(): SidebarState

Defined in: core/extensionAPI/modules/window/sidebarAPI.ts:322

Current sidebar layout state: 'expanded' | 'collapsed' | 'hidden'.

Example​
const isVisible = mscode.window.sidebar.state !== 'hidden';
Returns​

SidebarState