Using the Webview UI Toolkit for Visual Studio Code

Microsoft’s Visual Studio Code has become one of the most popular development tools out there. Mixing proprietary Microsoft features with an extensible open source core, it’s a quick install that can be configured to handle most languages and most platforms. It’s especially useful when working across platforms, as its remote development extensions allow you to use it on another device from your desktop whether it’s macOS, Windows, or Linux.

Under the hood, Visual Studio Code is a TypeScript application, running in an Electron runtime. That means it’s built on top of the open source Chromium browser engine used by Microsoft’s own Edge browser. More importantly, it’s the same engine as the Webview UI control that’s a key element of the Windows App SDK, which allows you to run JavaScript and TypeScript code inside your traditional Windows applications alongside HTML and CSS (Cascading Style Sheets) markup. Mixing the two approaches makes sense, and Microsoft is working on a Webview UI Toolkit to help bring Webview-based user experiences into VS Code.

Webview UI is an increasingly important tool, as it blends web tools with familiar Windows development environments. For example, you could write a management tool for a service that uses Windows-style UI, while rendering service web UI outputs in the same frame. So, it’s not hard to see how a tool using Webview UI could work with VS Code, providing a Chromium-compatible environment for existing web-based interfaces and dashboards, at the same time as hosting controls that use the same design language as the rest of the editor without being tied to Windows.

Although Microsoft recommends avoiding web views in Visual Studio Code extensions unless you “absolutely need them,” they’re increasingly important. Visual Studio Code may have started out as a tool for developing .NET systems programs and for general-purpose code editing, but it’s grown to become close to a full-fledged IDE, with support for tools such as Flutter that need a UI design surface alongside code. We’ve even seen Microsoft’s own browser tools team extend the F12 developer tooling into VS Code, using it to render debugging information.

What’s in the Webview UI Toolkit?

You can perhaps think of the Webview UI Toolkit as the Visual Studio Code equivalent of the Windows App SDK’s WinUI 3 component library. WinUI 3 offers the same controls across different UI frameworks, from web to PC. The Webview UI Toolkit takes a similar approach, offering a set of customizable controls that can give your extensions the same look and feel as the rest of VS Code. That way, if you’re rendering information from another application, you won’t be adding a cognitive deficit to users, ensuring that they stay in the same context as their code.

The controls support the same theming model as the rest of the editor. If your user picks a theme for the editor, your extension will automatically support it. As they’re web components, you’re not limited to any one set of development tools and can continue to develop extensions in your choice of web development frameworks.

With Visual Studio Code being used to host extensions from many different developers, supporting as many different languages, services, and servers as possible, it’s essential that they all have a common design. Developers need to be sure that the extensions they install work in and with VS Code, not loosely associating with it and then applying their own standards. We need to know that the same editor shortcuts work across all the extensions we’ve installed and that those extensions all behave consistently.

The toolkit is currently available as a public preview on GitHub, with some significant issues that make it not quite ready for production. A 1.0 release is planned for late 2022, so it’s worth starting to look at it even if you won’t be ready to ship code for some time.

Building a Webview-based VS Code extension

Microsoft provides a set of instructions for creating a Webview-based extension, along with prebuilt sample code. It’s much like building any other Visual Studio Code extension, at least during initial setup. Here you use the familiar Yeoman-based Extension Generator to set up the scaffolding for your extension. Don’t forget to install both Node.js and Git before using the generator, which then prompts you to answer a few basic questions to define your TypeScript code scaffolding.

Once the extension scaffolding has been created by Yeoman, edit the code in the default extension to add a panel class, with a render method that will be called by the extension’s activate function. The panel class is where your Webview code will be written, using the VS Code APIs to manage layout of panels within the VS Code frame. Your class will also need to clean up resources when users dismiss the Webview panel.

You can now start integrating Webview content into your extension, using the _getWebViewContent method to host your HTML. This is where you load any JavaScript libraries or CSS your extension will need. Once you have a basic framework for running a Webview-based extension, you can load and use the Webview UI Toolkit, installing it from npm into your extension’s directory. You can then add it to your extension by adding a set of new parameters to the _getWebViewContent method, adding a call to the Visual Studio Code Webview libraries and an extension URI. Remember to add these to any existing constructor or render methods if you’re updating existing extension code.

Consistent design for productivity and accessibility

Now that you have an extension with a Webview framework, you’re ready to add references to the toolkit URIs in your Webview HTML, loading them as JavaScript modules. Next, add the toolkit’s web components to your HTML. Although most of your code will be traditional JavaScript and HTML, the Visual Studio Code toolkit allows you to replace common HTML elements with components that have been designed to carry over the look and feel from the main VS Code application.

It’s important to note that Microsoft has designed its components to be ARIA compliant, with keyboard navigation built in, giving you additional accessibility features without needing extra code. These include common form elements, such as buttons and input areas, as well as check boxes and radio buttons. Other components are alternatives to familiar layout objects, adding a custom grid view for working with data and new progress rings and drop-downs. The current build offers what you should see as only an initial set of components, with more likely to come during the next few months. However, they will allow you to “Codify,” if you will, your existing application web UIs ready for use inside Visual Studio Code.

Using the Webview UI Toolkit won’t change how you write extensions for Visual Studio Code. In fact, it might make it harder, as the syntax associated with its components might not be the same as any you’re using elsewhere. But by giving VS Code extensions a consistent and themed set of accessible UI components, it will make your extensions more acceptable to users and help make them more productive. That’s a win for all of us.