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:
- Use the built-in product icons from Visual Studio Code. Reference it as:
$(icon-name)
; - 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)
; - 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
:
|
|
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:
|
|
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 thewidth
andheight
attributes of the image are set to16
; - 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 to1.83.0
, otherwise it might break your extension on older VSCode installations.