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 Related Labels macro lists all labels from every page which has one or more labels in common with the current page.

Using the Related Labels Macro

To add the Related 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).




Restrict to these Labels


Specify the labels for which you want to view related labels. For example, documentation,my:stuff.

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: related-labels

Macro body: None.

Storage format example

Wiki markup example


  1. Is it possible to get another view after clicking on an item in the related-labels list. I need to display the excerpt and don't want the spaces, other labels of each page and striplines.

    Optional a dropdown list including all related labels would be nice.

    1. Hi Robert,

      This feature is not currently supported. Perhaps you would like to modify the macro up to your likings.


      1. Anonymous

        How can this not be supported??? Imho it's a core functionality, without this feature labels are more or less useless.

  2. The Related-labels macro lists the labels commonly associated with the current page's labels.

    how do you define 'related' and 'commonly related'? i.e. what is the human-readable description of the algorithm used

    For instance, is it:

    • given one or more labels, list all labels used at least once on the same page as any of those labels?
    • given one or more labels, list all labels used at least once on the same page as some of those labels? (define some)
    • given one or more labels, list all labels used at least once on the same page as all of those labels?
    • given one or more labels, list the top n labels used most frequently on the same page as any of those labels? (define n)
    • given one or more labels, list the top n labels used most frequently on the same page as some of those labels? (define some, n)
    • given one or more labels, list the top n labels used most frequently on the same page as all of those labels? (define n)

    or some other definition?

    1. Hi James,

      To my understanding, the Related Labels Macro allows a page to display a list of labels that are 'related' to the labels used in the current page itself. Take for example this page where it has both the "documentation" and the "confluence-label-filter" labels. It would show all the labels resulted in the "Related Labels" section of the following link:

      If I have misinterpreted your questions, please further clarify them for a better understanding.


  3. Is there anyway we can render this macro as a heatmap like you can with the {popular-labels} macro?

    1. Hi Denise,

      You can render a list/heatmap of the most popular labels. For example:

      • count - (optional) Specify the number of labels to be displayed. If not specified, a default of 100 is used.
      • spaceKey - (optional) Restrict the popular labels to a certain space.
      • style - (optional) Allows 'heatmap'. Specifying a heatmap style will use different font sizes depending on their rank of popularity,
        ordered by label names. If not specified, a default list style is used ordered by popularity (highest first).


      1. This is now documented more thoroughly here: Popular Labels Macro.

  4. Anonymous

    Is there any style options for the macro There are no related labels. ?

    Like having them on a single line for i.e.

    1. Hi,

      I am not aware of style option available in the "Related labels macro". However, you can always raise a improvement request via Thanks.


  5. Anonymous

    There needs to be a wildcard function for labels.

    Say you're having students label all their Homework posts, in personal spaces, with a generic "HW", and then a "HW1", "HW2", as appropriate to each assignment. We should be able to populate a list of all tags on the site that read "HW*", no?

    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


      1. Is this macro open source? Are there other related plugins that provide this functionality? I need it too.

        Thanks, Martin.

  6. Hello,

    Is there a way to have the list of related labels sorted alphabetically? Actually, it's really a mess when you have more than 5-10 labels.


  7. Am I missing something? It seems that our macro is not listing related labels after a confluence upgrade to version 4.3.7.

    I can't find a specific bug in relation to this issue. Was wondering if there is an index I need to reset or a cache I need to flush.


  8. Is it possible to have this macro sort labels alphabetically?

    1. Hi Auren, sorry there is no parameter to sort the related labels macro.  According to this issue there are no plans to introduce this parameter.   CONF-21209 - Related Labels macro - add parameter to sort in alphabetical order Resolved

  9. When one clicks on a label on a page the labelled content is displayed, on the left the pages that contain the selected label, on the right a list of related labels. Does this also use this macro?

    And is there a limit to the number of related labels shown? To me it seems no more then 25 labels are shown.