These guidelines cover the best practices for creating extensions that seamlessly integrate with VS Code's native interface and patterns. In these guidelines, you can expect to find:
- An outline of VS Code's overall UI architecture and elements
- Recommendations and examples for UI contributed by an extension
- Links to relevant guides and samples
Before diving into the details, it's important to understand how the various architectural UI parts of VS Code fit together and how and where your extension could contribute.
The VS Code interface can roughly be divided into two main concepts: containers and items. Generally speaking, containers can be considered the larger sections of the VS Code interface that render one or more items:
The Primary Sidebar renders one or more Views. The Activity Bar and the Primary Sidebar are tightly coupled. Clicking on a contributed Activity Bar Item (read: View Container) opens up the Primary Sidebar where one or more View associated with that View Container will be rendered. A concrete example would be the Explorer. Clicking on the Explorer Item will open up the Primary Sidebar where the Folder(s), Timeline, and Outline Views are visible.
The Secondary Sidebar also functions as a surface for rendering a View Container with Views. Users can drag views like the Terminal or the Problems view to the Secondary Sidebar to customize their layout.
The Editor area contains one or more Editor Groups. Extensions can contribute Custom Editors or Webviews to open in the Editor area. They can also contribute Editor Actions to expose additional icon buttons in the Editor Toolbar.
The Panel is another area for exposing View Containers. By default, Views like the Terminal, Problems, and Output can be viewed in a single tab at a time in the Panel. Users can also drag views into a split layout much like they can do in the Editor. Additionally, extensions can choose to add View Containers specifically to the Panel instead of the Activity Bar/Primary Sidebar.
Extensions can add items to the various containers listed above.
Extensions can expose View-specific actions that appear as buttons on a View Toolbar.
Actions scoped to an entire View Container can also be exposed in the Sidebar Toolbar.
Extensions can contribution Editor Actions scoped to an editor directly in the Editor Toolbar.
The Panel Toolbar can expose options scoped to the currently selected View. For example the Terminal view exposes actions to add a new terminal, split the view layout, and more. Switching to the Problems view exposes a different set of actions.
Status Bar Item
On the left, Status Bar Items are scoped to the entire Workspace. On the right, items are scoped to the active file.
Common UI Elements
Extensions can contribute Commands that appears in the Command Palette to quickly execute some functionality.
Quick Picks capture a user's input in several different ways. They can ask for a single selection, multiple selections, or even freeform text input.
Notifications are used to communicate information, warning, and error messages to users. They can also be used to indicate progress.
Webviews can be used to display custom content and functionality for use cases that go beyond VS Code's "native" API.
In contrast to the Command Palette's consistent location, Context Menus give users the ability to perform actions or configure something from a specific location.
Walkthroughs provide a consistent experience for onboarding users to an extension via a multi-step checklist featuring rich content.
Settings enable users to configure options relevant to the extension.