Things to know when using custom icons for Visual Studio Code 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.

info More info on registering command can be found in the VSCode documentation.

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.

important Since version 1.83.0 of Visual Studio Code, there has been a change in how command icons are rendered in the UI.

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.

Before version 1.83.0:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": {
          "light": "path/to/light/icon.svg",
          "dark": "path/to/dark/icon.svg"
        }
      }
    ]
  }
}

Since version 1.83.0, you no longer have to specify the light and dark properties. You can specify the relative path to the SVG file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "contributes": {
    "commands": [
      {
        "command": "extension.sayHello",
        "title": "Hello World",
        "category": "Hello",
        "icon": "path/to/icon.svg"
      }
    ]
  }
}

Image specifications

Since the change in version 1.83.0, you need to make sure that your image file meets the following requirements:

• 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;
• Colors in the image will be ignored, so keep it single-colored;
• 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.

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

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.

important When changing to this new way of adding SVG command icons, make sure to set the VSCode engines property to 1.83.0, otherwise it might break your extension on older VSCode installations.