intellij-sdk-code-samples/topics/reference_guide/work_with_icons_and_images.md

Working with Icons and Images

Adding, organizing, and working with IntelliJ Platform and custom icons and images.

Code: AllIcons

Platform UI Guidelines: Icons list, Icons

Icons and images are used widely by IntelliJ Platform plugins. Plugins need icons mostly for , custom component renderers, , etc.

Plugin Logos, which represent a plugin itself, have different requirements than icons and images used within a plugin. For more information, see the .

Platform vs. Custom Icons

Plugins should reuse existing platform icons whenever possible. Use Icons list to browse existing icons. Platform icons are located in AllIcons. Icons from plugins are located in corresponding <PLUGIN_NAME>Icons class (e.g., GithubIcons).

If custom icons are required, please refer to detailed design guide. To generate SVG icons suited for the IntelliJ-based IDEs, also consider third-party web tool IntelliJ Icon Generator.

Organizing Icons

See Action Basics sample plugin as a reference.

In the case of a Gradle-based project, icons should be placed in the resources folder. If the project is DevKit-based, the recommended approach is to put icons to a dedicated source root marked as Resources Root, e.g., icons or resources.

If the icons are referenced only in plugin.xml attributes or elements, or in the @Presentation icon attribute, then they can be referenced by paths. In case the icons are referenced from the code and/or XML many times, it's convenient to organize them in an icons holder class.

Icons Class

Define a class/interface in a top-level package called icons holding icon constants as static fields:

package icons;

public interface MyIcons {
  Icon MyAction = IconLoader.getIcon("/icons/myAction.png", MyIcons.class);
  Icon MyToolWindow = IconLoader.getIcon("/icons/myToolWindow.png", MyIcons.class);
}

When using Kotlin, fields must be annotated with @JvmField:

package icons

object MyIcons {
  @JvmField
  val MyAction = IconLoader.getIcon("/icons/myAction.png", javaClass)
  @JvmField
  val MyToolWindow = IconLoader.getIcon("/icons/myToolWindow.png", javaClass)
}

The getIcon() method of IconLoader can be used to access the icons. The path to the icon passed in as argument to IconLoader.getIcon() must start with leading /.

Starting with 2021.2, *Icons class is not required to be located in icons package but can use plugin's package: icons.MyIcons → com.example.plugin.MyIcons.

{style="note"}

Using Icons

Icons defined inside plugin.xml with icon attribute for <action> or extension point, as well in @Presentation's icon attribute, can be referenced in two ways:

• by icon file path
• by icon constant in the icons holder class

To reference an icon by path, provide the path relative to the resources directory, e.g., for icons located in my-plugin/src/main/resources/icons directory:

<actions>
  <action icon="/icons/myAction.svg" ... />
</actions>

<extensions defaultExtensionNs="com.intellij">
  <toolWindow icon="/icons/myToolWindow.svg" ... />
</extensions>

In case of icons holder class, reference the icon constants. Note that if the class is located in the top-level icons package, name icons will be automatically prefixed and must not be specified. In case of placing the class in a custom package, the full package name must be provided, e.g.:

<actions>
  <!-- referencing icons from class in top-level 'icons' package -->
  <action icon="MyIcons.MyAction" ... />
</actions>

<extensions defaultExtensionNs="com.intellij">
  <!-- referencing icons from custom package -->
  <toolWindow icon="com.example.plugin.MyIcons.MyToolWindow" ... />
</extensions>

Image Formats

IntelliJ Platform supports Retina displays and has a bundled dark theme called Darcula. Thus, every icon should have a dedicated variant for Retina devices and Darcula theme. In some cases, you can skip dark variants if the original icon looks good under Darcula.

Required icon sizes depend on the usage as listed in the following table:

Usage	Icon Size (pixels)
Node, Action, Filetype	16x16
Tool window	13x13
Editor gutter	12x12

SVG Format

SVG (Scalable Vector Graphics) icons are supported since 2018.2.

{style="note"}

As SVG icons can be scaled arbitrarily, they provide better results in HiDPI environments or when used in combination with bigger screen fonts (e.g., in presentation mode).

A base size denoting the size (in the user space) of the rendered image in 1x scale should be provided. The size is set via the width and height attributes omitting the size units. If unspecified, it defaults to 16x16 pixels.

A minimal SVG icon file:

<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16">
  <rect width="100%" height="100%" fill="green"/>
</svg>

The naming notation used for PNG icons (see below) is still relevant. However, the @2x version of an SVG icon should still provide the same base size. The icon graphics of such an icon can be expressed in more details via double precision. If the icon graphics are simple enough so that it renders perfectly in every scale, then the @2x version can be omitted.

PNG Format

Use SVG icons for optimal results if your plugin targets 2018.2+.

{style="note"}

All icon files must be placed in the same directory following this naming pattern (replace .png with .svg for SVG icons):

Theme/Resolution	File name pattern	Size
Default	iconName.png	W x H
Darcula	iconName_dark.png	W x H
Default + Retina	iconName@2x.png	2*W x 2*H
Darcula + Retina	iconName@2x_dark.png	2*W x 2*H

The IconLoader class will load the icon that matches the best depending on the current environment.

Here are examples of toolWindowStructure.png icon representations:

Theme/Resolution	File name	Image
Default	toolWindowStructure.png
Darcula	toolWindowStructure_dark.png
Default + Retina	toolWindowStructure@2x.png
Darcula + Retina	toolWindowStructure@2x_dark.png

Animated Icons

Animated icons are a way to show that plugin is now performing some long-time action. For example, when plugin is loading some data.

Any animated icon is a set of frames that loop with some delay.

To create a new animated icon, use the AnimatedIcon. If you want to create an icon where frames follow each other with the same delay, use a constructor that accepts a delay and icons:

AnimatedIcon icon = new AnimatedIcon(
    500,
    AllIcons.Ide.Macro.Recording_1,
    AllIcons.Ide.Macro.Recording_2);

To create an icon from frames with different delays, use AnimatedIcon.Frame. Each frame represents an icon, and a delay until the next frame.

If you want to show somewhere that there is a long process, you can use the predefined AnimatedIcon.Default loader icon. This icon has a larger AnimatedIcon.Big version.

Icon Tooltips

Register resource bundle via com.intellij.iconDescriptionBundle extension point to provide tooltips automatically for all SimpleColoredComponent renderers.

Create icon.<icon-path>.tooltip key in given resource bundle, where <icon-path> is the icon path with leading slash and .svg removed and slashes replaced with dots (e.g., /nodes/class.svg → icon.nodes.class.tooltip).

Mapping New UI Icons

This feature is available since 2022.3.

To fully support New UI, the plugin must provide additional dedicated icons and mapping information. This allows supporting both UI variants at the same time — whichever the user chooses to use.

1. Create new expUi folder in your icon root folder (Reference).
2. Copy all icons for New UI in this folder.
3. Create empty $PluginName$IconMappings.json mapping file in the resources root folder.
4. Register $PluginName$IconMappings.json file in plugin.xml via com.intellij.iconMapper extension point.

Sample setup from Maven plugin:

• Icon resources root folder: images
• Mapping file: MavenIconMappings.json
• Extension point registration (<iconMapper mappingFile="MavenIconMappings.json"/>): plugin.xml

Mapping Entries

All New UI icons must be mapped in the $PluginName$IconMappings.json mapping file.

For each New UI icon, add a mapping entry inside expui block. Each folder starts a new block containing all its entries (see linked MavenIconMappins.json sample from above).

In this sample, the icon root folder is named icons:

{
  "icons": {
    "expui": {
      "folderName": {
        "expUiIcon1.svg": "icons/icon1.svg",
        "expUiIcon2.svg": "icons/icon2.svg"
      },
      "anotherFolder": {
        "expUiAnotherIcon.svg": "images/anotherIcon.svg"
      }
    }
  }
}

If one new icon replaces several old icons, use JSON list format. Example from PlatformIconMappings.json:

"vcs.svg": [
  "toolwindows/toolWindowChanges.svg",
  "vcs/branch.svg"
]