Related Labels Macro

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 Autocomplete for links, files, macros and mentions.

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

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

18 Archived comments

  1. User avatar

    Robert Zadeh

    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.

    16 Oct 2007
    1. User avatar

      Mei Yan Chan

      Hi Robert,

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


      19 Oct 2007
      1. User avatar


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

        06 Feb 2008
  2. User avatar

    James Mortimer

    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?

    14 Jul 2008
    1. User avatar

      Tony Cheah Tong Nyee

      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.


      15 Jul 2008
  3. User avatar

    Denise Van

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

    29 Jul 2008
    1. User avatar

      Fennie Ng

      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).


      30 Jul 2008
      1. User avatar

        Matt Ryall [Atlassian]

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

        17 Sep 2008
  4. User avatar


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

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

    06 Nov 2008
    1. User avatar

      Ming Giet Chong


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


      23 Dec 2008
  5. User avatar


    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?

    29 Aug 2010
    1. User avatar

      Sashidaran Jayaraman [Atlassian]


      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


      03 Sep 2010
      1. User avatar

        Martin Cleaver [Blended Perspectives]

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

        Thanks, Martin.

        27 May 2011
  6. User avatar

    Benjamin T.


    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.


    16 Jul 2013
  7. User avatar


    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.


    05 Aug 2013
  8. User avatar

    Auren Kaplan

    Is it possible to have this macro sort labels alphabetically?

    07 Feb 2014
    1. User avatar

      Rachel Robins [Atlassian Tech Writer]

      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

      17 Feb 2014
  9. User avatar

    Patrick Vanhoof

    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.

    11 Apr 2014
Powered by Confluence and Scroll Viewport