VS Code Extension UI/UX Development

Build secure, beautiful, and accessible VS Code extensions following official guidelines.

Quick Reference

UI Contribution	When to Use	Reference
Tree View	Hierarchical data, file explorers, outlines	tree-views.md
Webview	Custom UI beyond native API	webviews.md
Custom Editor	Replace default editor for file types	custom-editors.md
Sidebar View	Extension-specific panels	sidebars-panels.md

Core Principles

1. Native First, Webview Last

Prefer VS Code's native APIs over webviews:

Native API (preferred) → Tree Views → Webview Views → Full Webviews (last resort)

Native components are lighter, auto-themed, and accessible by default.

2. Security by Default

Every webview MUST have:

• Content Security Policy with nonces
• Validated message passing
• Restricted local resource roots

See security.md for implementation patterns.

3. Theme Integration

Use VS Code color tokens for automatic theme support:

/* Always use CSS variables, never hardcode colors */
.my-element {
  color: var(--vscode-foreground);
  background: var(--vscode-editor-background);
  border: 1px solid var(--vscode-panel-border);
}

See theming.md for complete token reference.

4. Accessibility Requirements

• All interactive elements keyboard navigable
• ARIA labels on focusable elements (concise, important info first)
• Color contrast ratios meeting WCAG 2.1 AA
• Screen reader announcements for dynamic content

See accessibility.md for implementation guide.

Extension Anatomy

my-extension/
├── package.json          # Manifest: activation, contributions, dependencies
├── src/
│   ├── extension.ts      # Entry: activate/deactivate functions
│   ├── providers/        # Tree, webview, editor providers
│   └── views/            # Webview HTML/CSS/JS
├── media/                # Icons, images, webview assets
└── resources/            # Static files (templates, schemas)

package.json Contributions

{
  "contributes": {
    "viewsContainers": {
      "activitybar": [{
        "id": "myExtension",
        "title": "My Extension",
        "icon": "media/icon.svg"
      }]
    },
    "views": {
      "myExtension": [{
        "id": "myTreeView",
        "name": "Explorer",
        "icon": "media/tree.svg"
      }]
    },
    "commands": [{
      "command": "myExtension.refresh",
      "title": "Refresh",
      "icon": "$(refresh)"
    }],
    "menus": {
      "view/title": [{
        "command": "myExtension.refresh",
        "when": "view == myTreeView",
        "group": "navigation"
      }]
    }
  }
}

UI Component Selection Guide

Need to display...
│
├─ Hierarchical data? → Tree View
│   └─ With custom rendering? → Tree View + TreeItem.iconPath/description
│
├─ Simple list? → Tree View (flat)
│   └─ With actions? → TreeItem.command + context menu
│
├─ Form/settings UI? → Webview View (sidebar) or Settings contribution
│
├─ Rich content preview? → Webview Panel
│
├─ Custom file editor? → Custom Editor
│   └─ Text-based? → CustomTextEditorProvider
│   └─ Binary/complex? → CustomEditorProvider
│
├─ Status/info? → Status Bar Item
│
└─ Quick input? → QuickPick / InputBox API

Common Patterns

Tree View with Actions

// Provider
class MyTreeProvider implements vscode.TreeDataProvider<MyItem> {
  private _onDidChangeTreeData = new vscode.EventEmitter<MyItem | undefined>();
  readonly onDidChangeTreeData = this._onDidChangeTreeData.event;

  refresh(): void {
    this._onDidChangeTreeData.fire(undefined);
  }

  getTreeItem(element: MyItem): vscode.TreeItem {
    const item = new vscode.TreeItem(element.label);
    item.iconPath = new vscode.ThemeIcon('file');
    item.contextValue = 'myItem'; // For context menu filtering
    item.command = { command: 'myExtension.openItem', title: 'Open', arguments: [element] };
    return item;
  }

  getChildren(element?: MyItem): MyItem[] {
    return element ? element.children : this.rootItems;
  }
}

// Registration
const provider = new MyTreeProvider();
vscode.window.registerTreeDataProvider('myTreeView', provider);
vscode.commands.registerCommand('myExtension.refresh', () => provider.refresh());

Secure Webview Panel

function createWebviewPanel(context: vscode.ExtensionContext) {
  const panel = vscode.window.createWebviewPanel(
    'myWebview',
    'My Panel',
    vscode.ViewColumn.One,
    {
      enableScripts: true,
      retainContextWhenHidden: true,
      localResourceRoots: [
        vscode.Uri.joinPath(context.extensionUri, 'media')
      ]
    }
  );

  panel.webview.html = getWebviewContent(panel.webview, context.extensionUri);

  // Handle messages from webview
  panel.webview.onDidReceiveMessage(
    message => {
      switch (message.command) {
        case 'alert':
          vscode.window.showInformationMessage(message.text);
          return;
      }
    },
    undefined,
    context.subscriptions
  );
}

function getWebviewContent(webview: vscode.Webview, extensionUri: vscode.Uri): string {
  const nonce = getNonce();
  const styleUri = webview.asWebviewUri(vscode.Uri.joinPath(extensionUri, 'media', 'style.css'));
  const scriptUri = webview.asWebviewUri(vscode.Uri.joinPath(extensionUri, 'media', 'main.js'));

  return `<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="Content-Security-Policy" content="
    default-src 'none';
    style-src ${webview.cspSource};
    script-src 'nonce-${nonce}';
    img-src ${webview.cspSource} https:;
    font-src ${webview.cspSource};
  ">
  <link href="${styleUri}" rel="stylesheet">
</head>
<body>
  <div id="app"></div>
  <script nonce="${nonce}" src="${scriptUri}"></script>
</body>
</html>`;
}

function getNonce(): string {
  let text = '';
  const possible = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
  for (let i = 0; i < 32; i++) {
    text += possible.charAt(Math.floor(Math.random() * possible.length));
  }
  return text;
}

Message Passing (Extension ↔ Webview)

// Extension side
panel.webview.postMessage({ type: 'update', data: myData });

panel.webview.onDidReceiveMessage(message => {
  // ALWAYS validate message structure
  if (typeof message !== 'object' || !message.type) return;

  switch (message.type) {
    case 'request':
      // Handle request
      break;
  }
});

// Webview side (main.js)
const vscode = acquireVsCodeApi();

// Restore state on load
const previousState = vscode.getState();
if (previousState) {
  restoreState(previousState);
}

window.addEventListener('message', event => {
  const message = event.data;
  switch (message.type) {
    case 'update':
      updateUI(message.data);
      // Persist state
      vscode.setState({ ...vscode.getState(), data: message.data });
      break;
  }
});

// Send message to extension
vscode.postMessage({ type: 'request', payload: data });

UI Toolkit Options (Post-2025)

The official @vscode/webview-ui-toolkit was deprecated January 2025. Alternatives:

Option	Pros	Cons
vscrui	React components, maintained	React dependency
Custom CSS	Full control, no deps	More work, theme sync
Codicons + CSS vars	Native look, lightweight	Limited components

For most cases, use VS Code CSS variables + Codicons for native appearance.

Checklist Before Publishing

• CSP configured for all webviews
• All colors use VS Code CSS variables
• Keyboard navigation works throughout
• ARIA labels on all interactive elements
• Message validation on both sides
• localResourceRoots restricted appropriately
• Extension activates only when needed (activation events)
• Icons use proper formats (SVG preferred)
• Tested with light, dark, and high contrast themes