Plugin and Panel Icons

Photoshop UXP Plugin API
,
1

Panel Icons

To use icons in your plugin, please follow these steps:

  1. Design your @1x scale icon at 23x23 and leave your icon a little border – this will ensure best rendering. You can use larger sizes, but the results may be blurrier.
  2. Export your icons with @1x and @2x scales. If you want, you can also export for 1.5 and 1.25x sizes as well. So, if your icon is named “pluginIcon”, the files should be:
    • panelIcon@1x.png
    • panelIcon@1.25x.png
    • panelIcon@1.5x.png
    • panelIcon@2x.png
  3. In your manifest, use the following form for each panel entrypoint (note that we’re assuming you exported the icons above into your plugin’s “icons” folder, and also note that you should only include the themes for which the icon is compatible – or use all to cover all themes):
    "icons": [
    {
        "width": 23, "height": 23, "path": "icons/panelIcon.png", "scale": [ 1, 1.25, 1.5, 2 ],
        "theme": [ "darkest", "dark", "medium", "light", "lightest", "all" ]
    }
]
    Note that the width and height determines the size of the icon in Ps right now, and not the actual resolution of your icon. Using anything other than 23x23 is probably going to render poorly.

With this, your plugin’s icon should be visible inside Photoshop (but not in the Plugin Panel).

Supporting Themes

Photoshop supports multiple themes, and you should create an icon that uses these themes.

Using themes is just like supporting a single icon, but now you have two entries inside icons and another set of icon files.

For example:

    "icons": [
        {
            "width": 23, "height": 23, "path": "icons/dark.png", "scale": [ 1, 2 ],
            "theme": [ "darkest", "dark", "medium" ]
        }, {
            "width": 23, "height": 23, "path": "icons/light.png", "scale": [ 1, 2 ],
            "theme": [ "lightest", "light" ]
        }
    ]

Here the “dark*.png” icons will be used when Photoshop is using the dark themes, and “light*.png” will be used when Photoshop uses the light themes.

You should seriously supporting themes with your icons, as not doing so may result in poor contrast when using certain themes.

Supporting multiple panels

Plugins can have more than one panel, and each panel can and should have its own icon. For example:

  "entrypoints": [
        {
            "type": "panel",
            "id": "runPanel",
            "icons": [
                {
                    "width": 23, "height": 23, "path": "icons/run-dark.png", "scale": [ 1, 2 ],
                    "theme": [ "darkest", "dark", "medium" ]
                }, {
                    "width": 23, "height": 23, "path": "icons/run-light.png", "scale": [ 1, 2 ],
                    "theme": [ "lightest", "light" ]
                }
            ]
        }
    ],
    "icons": [
        {
            "width": 23, "height": 23, "path": "icons/plugin-dark.png", "scale": [ 1, 2 ],
            "theme": [ "darkest", "dark", "medium" ]
        }, {
            "width": 23, "height": 23, "path": "icons/plugin-light.png", "scale": [ 1, 2 ],
            "theme": [ "lightest", "light" ]
        }
    ]

In the above example, the runPanel panel will show a separate icon.

You should supply a separate icon for each panel you support. If you don’t, the user may not be able to immediately determine which panel they’re trying to open, and your plugin may be rejected from the Plugin Marketplace.

The Plugin Icon

Plugins also need an icon for the Plugin Panel in Photoshop. This is a plugin-wide icon, and is not panel-specific.

This icon is 24x24 (@1x) and 48x48 (@2x). It should not be transparent. You should give yourself some space around the corners, since a rounded-corner treatment will be automatically applied in the Plugin Panel for you.

Plugin icons should be specified at the top level of the manifest. For example:

    "icons": [
        {
            "width": 48, "height": 48, "path": "icons/plugin.png", "scale": [ 1, 2 ],
            "theme": [ "darkest", "dark", "medium", "lightest", "light", "all" ],
            "species": [ "pluginList" ]
        }
    ]

Note that the above entry has 48x48 dimensions. This is a bug and will be fixed in the future to use be 24x24, but 48x48 must be used in the manifest to get the plugin panel to see it. In the future the key will be the species entry of pluginList.

In the above example, you’d have two icons in the icons folder: plugin@1x.png (24x24) and plugin@2x.png. (48x48).

Examples

Check the following samples for examples:

1 Like
3

Make sure you pay special attention to the panel icon filename. If you don’t have the “@1x” at the end of the name (before the extension), the panel icon will look fine on Mac but will not show up on Windows.

And the size suffixes (“@1x” etc.) go only on the filenames, not in the manifest file. So this icon:

panelIcon@1x.png

Is referred to in the manifest simply as “panelIcon.png”

2 Likes
4

Is there a reason for the 1px difference between plugin and panel icons? Maybe the panel minification icons have always been 23x23 in Photoshop so that couldn’t be changed?

I was just wondering, because if both were equal in size (either 23px or 24px) we could reuse icons for single-panel-plugins :blush:

5

The two icons have different use cases:

  • The 23x23 icons are made to fit inside the Ps toolbars, and because the resolution is odd, makes it possible to have truly centered horizontal and vertical lines (good for tool-like icons). This icon can be transparent as well.
  • The 24x24 icons are made to render inside the plugin panel, and are intended more for a logo rather than an action. There the “tool-like” nature of the toolbars doesn’t have the same weight, and so here it makes sense to have them be close to the marketing icons (which are 48x48, 96x96 and 192x192). As such, you can just down-rez the 48x48 icon for @ 1x devices. This icon always has some extra treatment applied (rounded corners) and should not be transparent.

Think of the panel icon as a “tool”, and the plugin panel as a “logo”. :slight_smile:

2 Likes
6

In the main Adobe Plugin Panel, can you specify different 48x48px icons for the Dark and Light themes or is it just one icon across all themes.

7

What’s the point of icons for a command based plugin?
They are not shown anywhere, but still mandatory

8

They’re shown in the Plugin Panel. You don’t need an icon per command, but you at least need an icon for the plugin itself.

9

But if a plugin doesn’t have a panel? My plugin is three commands only. No need for a panel of 3 buttons :slight_smile:

10

No, that’s not what I meant – In Ps (and XD), there’s a Plugin Panel that shows all installed plugins. In Ps, navigate to Plugins > Plugins Panel. All installed plugins are listed there, including the plugin’s icon.

11

Oh, I see :slight_smile: Good thing you mentioned that, because even if I changed icons to my own, it still shows the default starter template Lego brick icon :confused: Can it be some cache or something? I kept icon names the same as in starter plugin. Icons are 23x23 @1x and 46x46 @2x

12

I give up :frowning:

Tried 23x23, tried 24x24, tried saving with Convert to sRGB checked and without, tried restarting Ps, but I still can’t see my icons :confused:

Icons are grayscale PNGs with alpha channel

image
image1086×302 18.4 KB

13

Check my response here - only changing dimensions in manifest to 48 helped.

@kerrishotts, I believe something is definitely broken. Or it should be documented somewhere if it’s intentional.

14

Where do we change the icon that is displayed on the Creative Cloud Desktop app?

15

IIRC locally installed plugins don’t show the icon if you’re wondering about that

1 Like
16

Correct – plugins distributed outside of the marketplace will not show the icon inside the Creative Cloud Desktop app. (The icon will be visible inside Photoshop, however.)

1 Like
17

This post would make a great addition to the documentation perhaps even verbatim

18

Why doesnt the UXP Dev tool add these to to the manifest when using the starter template

19

@IanBarber – in the past when we’ve included icons in starter projects, they tend to find their way into the version submitted to the marketplace… which then results in a rejection to the dev, because it’s not good for users to see a list of plugins all using the starter icons with no way to differentiate between them.

(Note: not saying we wouldn’t add the icons to the starter project… but that it’s… complicated :slight_smile: ).