UX Guidelines
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.
Containers
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:
Activity Bar
The Activity Bar is a core navigation surface in VS Code. Extensions can contribute items to the Activity Bar that function as View Containers that render Views in the Primary Sidebar.
Primary Sidebar
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.
Secondary Sidebar
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.
Editor
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.
Panel
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.
Status Bar
The Status Bar provides contextual information about the workspace and currently active file. It renders two groups of Status Bar Items.
Items
Extensions can add items to the various containers listed above.
View
Views can be contributed in the form of a Tree View, Welcome View, or Webview View and can be dragged around to other areas of the interface.
View Toolbar
Extensions can expose View-specific actions that appear as buttons on a View Toolbar.
Sidebar Toolbar
Actions scoped to an entire View Container can also be exposed in the Sidebar Toolbar.
Editor Toolbar
Extensions can contribute Editor Actions scoped to an editor directly in the Editor Toolbar.
Panel 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
Command Palette
Extensions can contribute Commands that appears in the Command Palette to quickly execute some functionality.
Quick Pick
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
Notifications are used to communicate information, warning, and error messages to users. They can also be used to indicate progress.
Webviews
Webviews can be used to display custom content and functionality for use cases that go beyond VS Code's "native" API.
Context Menus
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
Walkthroughs provide a consistent experience for onboarding users to an extension via a multi-step checklist featuring rich content.
Settings
Settings enable users to configure options relevant to the extension.
