Documentation for Confluence 5.8 (Server).
Documentation for Confluence Cloud and earlier versions of Confluence is available too.

Skip to end of metadata
Go to start of metadata

The Popular Labels macro displays the most popular labels used throughout your Confluence site or within a space. A popular label is a label that has been added to many pages. 

Using the Popular Labels Macro

To add the Popular Labels macro to a page:

  1. In the Confluence editor, choose Insert > Other Macros
  2. Find and select the required macro

Speeding up macro entry with autocomplete: Type { and the beginning of the macro name, to see a list of suggested macros. Details are in Using Autocomplete.

To edit an existing macro: Click the macro placeholder and choose Edit. A macro dialog window will open, where you can edit the parameters of the macro.


Parameters are options that you can set to control the content or format of the macro output. Where the parameter name used in Confluence storage format or wikimarkup is different to the label used in the macro browser, it will be listed below in brackets (example).




Number of Labels to Display


Specifies the total number of labels to display in the heatmap.

Restrict Labels to this Space Key


Restricts the list of popular labels to the specified space.

Style of Labels


  • list – displays the popular labels as a bulleted list, ordered by popularity (highest first).
  • heatmap – displays the popular labels using different font sizes for each label depending on the label's popularity, ordered by label names.

Code examples

The following examples are provided for advanced users who want to inspect or edit the underlying markup for a Confluence page. 

Macro name: popular-labels

Macro body: None.

Storage format example

Wikimarkup example


  1. This macro is working fine and displaying popular labels for the space I'm working with, but when you click one of the labels, the results show matches from all spaces the user can access -- how can I get the results to show only matches for the label within the current space?

    1. Hello jamiep77,

      Unfortunately, it's currently not possible to restrict the results of this macro to those restricted by its spaceKey parameter.

      However, this issue has already been raised in CONF-9149 and you can vote on it to increase its chances of being fixed in a future version.

      Best regards,

      Giles Gaskell
      Technical Writer

      1. Thank you so much for the info -- I've voted on CONF-9149.

  2. I have modified the Popular Labels macro a bit since the standard version didn't fit my needs. The patched version supports customizing using CSS and sorting by label name and rank. You can download it here: Popular Labels Macro Tutorial.

    1. Nice one Arne, I'm looking for a way to change the background colour to transparent or white, your version looks like it might fit the bill nicely (smile)

      I was trying to simply use the style against the site, however all the styling on the heatmap is at the element level which can't be overridden.

  3. In Confluence 2.10.2, this macro does not seem to order by name, even if I use "style=heatmap" as indicated above.  It orders by popularity instead.  How can I order by name?

    1. Hi Craig,

      This is because of the existing bug,, in which the ordering by name does not work without the spaceKey parameter. The "heatmap" style will order by popularity if spaceKey parameter is used.


      In your scenario, are you trying to get the popular labels for the entire Confluence instance or just a space? If it is just a space, then putting the spaceKey parameter will solve it. Unfortunately, if it is a global popular labels you are aftering, we need to wait CONF-13594 to be resolved.

      sorry for any inconvenience caused,
      Henry CL Tiong

      1. Thank you Henry.  So, my next question is can a variable for spaceKey be used so the macro is still usable in a global template?  If not, is there another more usable heat map macro or plugin for labels?   Thanks in advance!

        Edit: I should clarify that I am looking for space-specific labels, but would like to use the macro in a global template.

        1. Hi Craig,

          You might want to create a user macro that can supply the current space key to the {popular-labels} macro:

          1. Create a user macro
            • Macro name: popular-heatmap
            • Untick "Macro has a body"
            • Output: Macro generates wiki markup
            • Template:
          2. Create a global template that calls the {popular-heatmap} macro we have just created.

          Now, the macro displays space-specific labels. Hope that helps!


  4. Anonymous

    Is it possible to restrict the user to view only those labels in space that the user has access to?

    1. Hi,

      As far as I know, I have tested it in Confluence 2.10.3 and Confluence 3.0. Unfortunately, the feature requested is not available yet. However, you might want to raise an improvement request in JIRA:

      Hope that helps,

  5. Anonymous

    I'd like to list all spaces having with a specific team label. My goal is to display clusters of spaces grouped by team-lables. I've looked for space-specific macros but none provided me with a filter for team-lables. Any idea?

    Thx in adavance


    1. Hi GuL,

      I think this is achievable by using the reporting plugin. Here is a sample code that works for me:

      Hope this helps.


      1. Anonymous


        great! Exactly what I was looking for!


        1. Glad it worked for you, GuL!


  6. Anonymous


    We have lots of pages labelled rss_ that I dont want to appear in a cloud,  so is there a way to exclude certain labels in a space?

    1. Hi,

      I am afraid that this is not currently possible. Feel free to raise a feature request at and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page


  7. Anonymous


    do you guys know a way to display a tag cloud in confluence with a time restriction of the tags - let's say a tag cloud that displays the most popular labels of the last month? The most popular tags in our wiki don't change too often, so it's a bit boring to always display the same labels.

    Any help is greatly appreciated!

    1. Hi,

      I am afraid that this is not currently possible. Feel free to raise a feature request at and describe in detail how you require this feature to work. Please add yourself as a watcher, vote for this feature and add your own comments to this feature request. For further details on how we include new features and improvements, you might want to read this page.

      You could also get more help in our Atlassian Answers.


  8. Anonymous

    Hi ,

    Can we make certain pages specific rather than complete space?


  9. Anonymous


    I meant labels specific to certain pages rather than space.


    1. Hi

      I meant labels specific to certain pages rather than space.

      I have a mere suggestion, you might want to try the Page Family Tag Cloud. Hopefully this plugin will satisfy some of your requirement.

      Hope that helps.
      Best rgds,

  10. Anonymous

    Is it possible to add a narrow heatmap in line with (ie as a section of) the left hand menu?

    I have tried a few options in the 'Navigation' page and failed (popular labels did appear as menu line items). In heat-map form, I only seem to get the panel spanning the full page.

    Thanks in advance for any advice


  11. Hi,

    Is it possible to exclude certain labels?

    For example I've created a blog using confluence but in order for the post to appear they all have to use a certain label. I'd like to exclude this lablel from the heatmap.



    1. Hi James,

      I am afraid currently it is not possible to exclude certain labels using popular labels macro. Feel free to raise an improvement request at And describe in detail how you require this improvement to work. Please add yourself as a watcher for this improvement and add your own comments to this improvement request.

      Meanwhile, you can do that by using Tag Cloud Macro plugin along with excludePrefix or excludePostfix paramater.
      For example, if you want to display the most popular labels (excluding "book" and "cat") using Tag Cloud Macro plugin, you can write a macro like this:

      Please take note that you may need to read its documentation here for further usage.

      Hope that helps (smile).
      Husein Alatas

      1. Hussein,

        Is there a difference between the Tag Cloud Macro and the Page Family Tag Cloud? we have the latter installed and I'm wondering whether we could use this to exclude certain labels?



        1. Hi,

          Based on the documentation of Page Family Tag Cloud, it looks like it doesn't have such parameter to exclude certain labels. And also please take note that currently it's not supported in Confluence 3.1.x above.

          To know more on the differences, you can read the documentation of Page Family Tag Cloud and Tag Cloud Macro.

          Husein Alatas

  12. How can I use spaceKey=current in this macro? If I use this in a template or a sidebar I'd like it to populate with only data from the current space.

  13. Hi,

    What determines the popularity of a label--the number of times it appears or the number of times users click on the label?


  14. I installed 4.0-rc7 and the popular labels macro showed all labels in a list fashion even though I choose the heatmap style. Those labels are still shown in different font sizes based on their popularities but being rendered in a list rather than a tag cloud wastes screen real estate. Can this be changed back to tag cloud display? Thanks.

    1. It's the same in full retail 4.0 version (as you can see in one of the first comments on this page). Heat map style is not working properly yet (sad)

  15. Anonymous

    Hi, would also like to have the "heatmap" style working instead of a list. With the conversion to 4.0 all popular labels are listed.

    The heatmap was a nice visible tag on the main pages.

  16. Hi,

    I just installed confluence on my PC and the fonts of the 'Popular Label' macro are not uniform (their sizes vary). Is there any configuration i can make so as to ensure all the text fonts of labels captured by the Popular 'Label macro' are uniform?

    Will highly appreciate a response to this.



    1. it's a way to show the different popularity of the labels and is meant to be this way.

      1. Hi Qian,

        Thanks so much for your response. I really appreciate. It explains a whole lot.

        I actually have a new space now with all fonts in the Popular label macro being of the same size now. But they are quite big and desire reducing thier sizes so as to be quite small.

        Is it possible to reduce their sizes?


        1. Hi Christian, there's no way to change the appearance of this macro. It is designed to be like a tag cloud, with more popular labels larger than less popular ones. 

          One of other label macros (such as labels list, or related labels) might work better for you if you need a particular layout.