Working with Icons

Plugins should reuse existing platform icons whenever possible.

Use the Icons list to browse existing icons. Platform icons are located in AllIcons. Icons from plugins are located in the corresponding <PLUGIN_NAME>Icons class (e.g., GithubIcons).

If custom icons are required, refer to detailed design guide.

tip

See Action Basics sample plugin as a reference.

In the case of a Gradle-based project, icons should be placed in the resources directory. 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 icon holder class.

package icons;

public interface MyIcons {
  Icon Action = IconLoader.getIcon("/icons/action.svg", MyIcons.class);
  Icon ToolWindow = IconLoader.getIcon("/icons/toolWindow.svg", MyIcons.class);
}

package icons

object MyIcons {
  @JvmField
  val Action = IconLoader.getIcon("/icons/action.svg", javaClass)
  @JvmField
  val ToolWindow = IconLoader.getIcon("/icons/toolWindow.svg", javaClass)
}

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 icon 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 the case of icon 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>

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:

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

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

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

To create a new animated icon, use the AnimatedIcon. 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.

Use the predefined AnimatedIcon.Default loader icon to indicate a long process. This icon has a larger AnimatedIcon.Big version.

tip

Add true AnimatedIcon.ANIMATION_IN_RENDERER_ALLOWED client property to list, table, and tree components to repaint animated icons automatically. See ANIMATION_IN_RENDERER_ALLOWED's Javadoc for details.

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

Create icon.<icon-path>.tooltip key in a 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).

tip

See UI Kit for guidelines and overview.

To fully support the New UI, the plugin must provide additional dedicated icons and mapping information. This allows supporting both UI variants at the same time, depending on what the user has selected.

tip

Sample setup from Maven plugin:

• Icon resources root directory: images

• Mapping file: MavenIconMappings.json

• Extension point registration (<iconMapper mappingFile="MavenIconMappings.json"/>): plugin.xml

{
  "icons": {
    "expui": {
      "dirName": {
        "icon1.svg": "icons/icon1.svg",
        "icon2.svg": "icons/icon2.svg"
      },
      "anotherDir": {
        "anotherIcon.svg": "images/anotherIcon.svg"
      }
    }
  }
}

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