Working with Icons
Edit pageLast modified: 17 December 2024Code: AllIcons
UI Guidelines: Icons list, Icons
Icons are used widely by IntelliJ Platform plugins. Plugins need icons mostly for Actions, custom component renderers, Tool Windows, etc.
tip
A plugin logo, which represents the plugin itself, has different requirements than icons used within plugins. For more information, see the Plugin Logo section.
Platform vs. Custom 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.
Organizing Icons
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.
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 Action = IconLoader.getIcon("/icons/action.svg", MyIcons.class);
Icon ToolWindow = IconLoader.getIcon("/icons/toolWindow.svg", MyIcons.class);
}
When using Kotlin, fields must be annotated with @JvmField
:
package icons
object MyIcons {
@JvmField
val Action = IconLoader.getIcon("/icons/action.svg", javaClass)
@JvmField
val ToolWindow = IconLoader.getIcon("/icons/toolWindow.svg", 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 /
.
note
Starting with 2021.2,
*Icons
class is not required to be located inicons
package but can use plugin's package:icons.MyIcons
→com.example.plugin.MyIcons
.
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 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
<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>
Icon 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 |
Editor gutter (New UI) | 14x14 |
SVG Format
note
SVG (Scalable Vector Graphics) icons are supported since 2018.2.
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 (Deprecated)
warning
Use SVG icons for if your plugin targets 2018.2+.
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 | Icon |
---|---|---|
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 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. SeeANIMATION_IN_RENDERER_ALLOWED
's Javadoc for details.
Icon Tooltips
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
).
2022.3+New UI Icons
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.
Setup
Create a new expui directory in the icon root directory (Reference).
Copy all icons for the New UI into this directory.
Create an empty $PluginName$IconMappings.json mapping file in the resources directory.
Register $PluginName$IconMappings.json in plugin.xml via the
com.intellij.iconMapper
extension point.
tip
Sample setup from Maven plugin:
Icon resources root directory:
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 directory starts a new block containing all its entries (see linked MavenIconMappings.json
sample from above).
In this example, the icon root directory is named icons:
{
"icons": {
"expui": {
"dirName": {
"icon1.svg": "icons/icon1.svg",
"icon2.svg": "icons/icon2.svg"
},
"anotherDir": {
"anotherIcon.svg": "images/anotherIcon.svg"
}
}
}
}
If one new icon replaces several old icons, use a JSON list. Example from PlatformIconMappings.json
:
"vcs.svg": [
"toolwindows/toolWindowChanges.svg",
"vcs/branch.svg"
]
New UI Tool Window Icons
The New UI uses outlined icons for tool windows that have a size of 20x20 pixels and 16x16 pixels in compact mode. Plugin developers who want to provide all necessary variants of their tool window icons use the following suffix scheme for their icon filename, here referred to as iconToolWindow:
iconToolWindow.svg: a 16x16 pixels compact mode variant of the icon for the light theme.
iconToolWindow_dark.svg: a 16x16 pixels compact mode variant of the icon for the dark theme.
iconToolWindow@20x20.svg: a 20x20 pixels variant of the icon for the light theme.
iconToolWindow@20x20_dark.svg: a 20x20 pixels variant of the icon for the dark theme.
New UI Icon Colors
To work as expected, the New UI requires specific colors for icon content. This is necessary for situations where tool window buttons are active, during which the background is highlighted. To enhance contrast, the IntelliJ Platform dynamically alters the icon's content color to white.
Hence, for the creation of light and dark mode variants, plugin authors must use the following prescribed colors within their icons:
Theme | Color Code |
---|---|
Light |
|
Dark |
|
note
Thanks for your feedback!