Getting started

What is VSCode Elements?

The “webview API” enables extensions to build entirely customizable views within Visual Studio Code. While the VSCode API grants access to different UI elements, none of these UI widgets are functional in the “webview.” VSCode Elements addresses this by re-implementing these UI controls as web components (aka custom elements), and introducing some new ones. This allows for the creation of user interfaces that look like the native user interface of VSCode.

You may not need VSCode Elements

If you prefer traditional HTML and CSS over JavaScript, or if you’d rather avoid adding a new dependency, consider checking out the VSCode Elements Lite project. It offers a collection of HTML and CSS snippets that, in many cases, are perfectly suitable. This approach is both simple and robust.

Installation

You can access the library as NPM package:

1
npm i @vscode-elements/elements

Including the bundled version

This is the most straightforward method, and while it may not be the most optimized, it gets the job done.

1
<script
2
  src="node_modules/@vscode-elements/elements/dist/bundled.js"
3
  type="module"
4
></script>

Importing only necessary components

1
import "@vscode-elements/elements/dist/vscode-button/index.js";

Usage

The imported components will be automatically registered. Once registered, Vscode Elements can be used like standard HTML elements. A standard default view can be provided using the :defined() pseudo-class until the element is registered.

1
vscode-buttton:not(:defined) {
2
  display: inline-block;
3
  height: 26px;
4
  visibility: hidden;
5
  width: 100px;
6
}

Properties and attributes

Custom elements are configurable through properties and attributes. Properties used in JavaScript while attributes are used in HTML.

An example of using a property:

1
const badge = document.querySelector("vscode-badge");
2
badge.variant = "activity-bar-counter";

An attribute example

1
<vscode-badge variant="activity-bar-counter"></vscode-badge>

The attribute name may differs from the property name. In the API documentation, the attribute corresponding to the property is always indicated if it exists.

Attribute and property reflection

Property reflection means that the related attribute will be synchronized when the property is changed. When a property is reflected it will be indicated with the reflects badge in the API documentation.

Methods

Methods are callable functions on the element instances.

1
const textfield = document.querySelector("vscode-textfield");
2
textfield.reportValidity();

Events

Most of the components dispatch events.

1
const tabs = document.querySelector("vscode-tabs");
2
tabs.addEventListener("vsc-tabs-select", () => {
3
  console.log("A tab has been selected.");
4
});

Most of the components use native events if possible. When a component has a custom event, the event is exported as a TypeScript type. All exported events are descendants of the CustomEvent class.

1
import type { VscTabsSelectEvent } from "@vscode-elements/elements/dist/vscode-tabs/vscode-tabs";

Slots

Slots are used to accept HTML content. The default slot, which is the content between the HTML tags, is the most common slot:

1
<vscode-button>Click here</vscode-button>

Many components have named slots. In the following example the badge component is placed in the decorations slot.

1
<vscode-collapsible title="Decorations example" class="collapsible">
2
  <vscode-badge variant="counter" slot="decorations">99</vscode-badge>
3
  <p>
4
    Suspendisse potenti. Maecenas eu egestas metus. Nulla eget placerat mi, et
5
    efficitur augue.
6
  </p>
7
</vscode-collapsible>

Custom CSS properties

The appearance of VSCode elements can be configured using custom CSS properties. These variables are provided by VSCode, and in most cases, it is not recommended to change them manually, although they can be modified if necessary.

1
vscode-button {
2
  --vscode-button-hoverBackground: red;
3
}