Things to know when using custom icons for VSCode commands

You can specify an icon when adding commands to your Visual Studio Code extension. These icons are rendered when you register the commands, such as the explorer title bar, document title bar, and more.

You have three options for specifying the icon:

1. Use the built-in product icons from Visual Studio Code. Reference it as: $(icon-name);
2. Use an icon font that you can define in your contributes.icons section. Once you have defined the icon font, you can reference it as: $(icon-name);
3. Use an image (SVG, png, …) to specify the icon.

This change in version 1.83.0 made me write this article, as it affected one of my extensions.

Using SVGs as icons

When you want to use an image file as an icon, you can specify the path to the image file in the icon property of the command. The path is relative to the extension root.

1
{
2
  "contributes": {
3
    "commands": [
4
      {
5
        "command": "extension.sayHello",
6
        "title": "Hello World",
7
        "category": "Hello",
8
        "icon": {
9
          "light": "path/to/light/icon.svg",
10
          "dark": "path/to/dark/icon.svg"
11
        }
12
      }
13
    ]
14
  }
15
}

Image specifications

• The size of the image should be 16x16 pixels. When using an SVG, make sure that the width and height attributes of the image are set to 16;
• SVG is recommended, but you can, for instance, use a PNG file as well.

What changed in version 1.83.0?

To explain this, we need to look at how these icons were rendered in the UI. In the versions older than 1.83.0 of Visual Studio Code, the icons were added as the background image of the element in the UI.

Show image

In the newer versions of Visual Studio Code, the icons are added as a background mask to the element.

Show image

As images are now used as a mask, the need for a light and dark version of the icon is not required anymore.

The current Visual Studio Code theme determines the color of the icon. Behind the scenes, the --vscode-icon-foreground CSS variable is used for it.

This change gives the VSCode team and theme authors more control of the icon. For instance, before, you could use a colored icon, but right now, as it is used as a mask, this always renders in the same color.

Update

In version 1.83.1 they reverted the masking logic to how icons where originally loaded. More information on: Theme colour applied to SVG icons.