Can't get web item icon to display


Try as I might I cannot get my plugin’s web-item in the sidebar of the Repository context to display the specified icon. I’ve scoured the developer community, stack overflow, the source code … nothing I try works.

My atlassian-plugin.xml looks like this

<?xml version="1.0" encoding="UTF-8"?>
<atlassian-plugin key="${atlassian.plugin.key}" name="${}" plugins-version="2">

        <description>My plugin</description>
        <vendor name="${}" url="${project.organization.url}" />
        <param name="plugin-icon">images/logo-16.png</param>

    <resource type="i18n" name="i18n" location="bitbucket-plugin"/>

        name="Web Resources"
        <resource type="soy" name="soyui" location="/templates/"/>
        <resource type="download" name="images/" location="/images"/>

        name="Plugin Servlet"

        name="Repository Plugin Web Item"
        <label key="repo-plugin-web-item.label">MyPlugin</label>
        <icon height="16" width="16">
            <link linkId="repo-plugin-web-item.icon">/download/resources/com.mycompany.bitbucket-plugin:bitbucket-plugin-resources/images/logo-16.png</link>
        <link linkId="">/plugins/servlet/myplugin/repo/$</link>


I’ve tried any number of url permutations:




Nothing works. I always get the aui-dialog close icon instead (no idea why - seems a strange default). However if I manually enter the full url (as shown in the atlassian-plugin.xml file above) into my browser, the icon is displayed! What gives?

Any ideas?

Many thanks in advance…

If it is displaying the aui-dialog close icon - there is the possibility of some name clash (ie it’s icon is also named logo-16?

I would try the /images/name.png method with a more unique name.

Thanks for the response but I don’t think that’s it. I simplified the xml somewhat for the post (removed some prefixes etc). The actual image name is unique. I should also mention that the aui-icon aui-icon-small aui-iconfont-close-dialog icon is displayed even if I completely remove the icon from my atlassian-plugin.xml file.

I tried the following too:

<link linkId="plugin-web-item.icon" absolute="true">
    $webResourceManager.getStaticPluginResource("${atlassian.plugin.key}:bitbucket-plugin-resources", "/images/logo-16.png")

nope :frowning:

Hi @a.webster,

To add an icon to the web-item on the navigation sidebar you will have to use this syntax:

        <param name="iconClass" value="aui-icon-small aui-iconfont-world"/>

The value provided to the iconClass param can be any CSS class name. In the example above, I’m using the AUI icons that you can find here: Icons - AUI Documentation

On the AUI page, if you click on the icon that you want to use, you will get a code snippet similar to this one:

<span class="aui-icon aui-icon-small aui-iconfont-world">
   Insert meaningful text here for accessibility

From the class attribute, you need to extract two values, e.g. aui-icon-small aui-iconfont-world and pass them to the web-items iconClass param.

If you wish to use a custom icon, then you will have to:

  • create a Less file inside your plugin project and add the new web-resource definition to the atlassian-plugin.xml file:

      <web-resource key="some-resource-key">
         <resource type="download" name="my-css-file.css" location="my-css-file.less" />
         <resource type="download" name="my-icon.png" location="my-icon.png">
         <context>bitbucket.layout.repository</context> <!-- we want to load those files or all repository pages -->
         <transformation extension="less">
             <transformer key="less-transformer" />
  • create a custom CSS class e.g. my-plugin-icon-class and add it to the Less file:

    .my-plugin-icon-class {
       background-image: url('my-icon.png');
       /* Insert here any other CSS styles you need */
  • Pass the class name param to your web-item:

       <param name="iconClass" value="my-plugin-icon-class"/>

Let me know if that works. Unfortunately, you stepped on the undocumented part of the plugin development for Bitbucket DC.

Maciej Adamczak
Atlassian Developer

1 Like

OMG finally! Thanks ever so much, you are a life-saver!


edit - (ps. “finally” as in “finally it works”, not as in “finally someone answered”! I’m most appreciative of any help/experiences community members have graciously taken the time to offer)

1 Like