This content applies to the legacy editor and the new editor.

Labels are key words that you can add to pages and attachments to make them easier to group and find. For example, you could assign the label accounting to all accounts-related pages on your site. You can then browse all pages with that label in a single space or across the site, display a list of pages with that label, or search based on the label. 

You can also use labels to categorize spaces. Head over to the page to learn more about using space labels to keep Confluence neat and organized.

Label a page

Any user with permission to edit a page can add labels to it. Any existing labels appear at the bottom-right of the page, below the page content.

To add a label to a page:

  1. While viewing a page or blog, choose the edit icon  next to the list of labels or press L on your keyboard.
    You can also do this while creating or editing a page, by choosing the label icon  at the top of the page.
  2. Enter a new label (existing labels are suggested as you type), then click Add

Label an attachment

  1. Do either of the following:
    • On the page that contains the attachment: Go to Actions menu icon > Attachments
    • Click on the space name in the navigation.  Click Space Settings (), > Content tools tab > Attachments

    You'll see a list of attachments, with any existing labels listed in the Labels column.
  2. Choose the edit icon  beside the list of labels and type in a new label (existing labels are suggested as you type), then click Add.

You can also add labels in a list of attachments displayed by the Attachments macro, by choosing the edit icon  beside each label.

tip/resting Created with Sketch.

Labels do not accept spaces, and are lower case only. This means that you can type in multiple labels at once just by adding spaces between each label, and that any capitals will be automatically converted to lower case. If you want to use a label that has more than one word, try using an underscore or hyphen, like so: this_is_a_label or this-is-a-label.

View labels

View all content with a specific label in a space or site

When viewing a page or post that has labels, or that displays the Attachments macro, choose any label to go to the Labeled content page for that space. This displays a list of all the pages in that space, with that label. To see all content on the site with that label, choose the cog iconSee content from all spaces. 

View all labels in a space or site

From the labeled content page, click on the cog icon > all labels to see all the labels in that space.

Alternatively, use the following URL. Make sure you use your own site address, and replace SPACEKEY with the actual space key of a space.


At the top of the page, there'll also be an option to see all labels across the site. 

View popular labels in a space or site

From the other views, you can click on the cog icon and select Popular Labels. This displays a word cloud, where the bigger a label is displayed, the more popular it is. There's also an option to see popular content across whole site. 

Screenshot: The Labeled content page    

Search by label

You can use the labelText: prefix to search for content that has a specific label. For example, if you're looking for pages with the label chocolate, type labelText:chocolate into the search field in the Confluence header. For more examples of searching by label, see Confluence Search Syntax.

Search for labeled pages using a URL

In your browser's address bar, enter the following URL and press enter: http://<>/label/jon+snow

The Labeled content page will load, displaying all pages that have both of the labels jon and snow. Replace jon and snow with the label(s) you want to search for, and separate multiple labels with a + symbol.

Remove labels

 When viewing page, blog post, or attachment labels, an x appears alongside each label. Choose the x to remove the label. To delete a whole category of labels, you'll need to remove that label from everywhere it appears.

If you have deleted pages that contain a label, you may need to purge the deleted pages from the space's trash to ensure that the label disappears too.

Use macros to categorize or display labels

Using labels and macros, you can categorize pages, blogs, and attachments, and display them in Confluence in a number of ways.

As an example, you could label all pages relevant to the marketing team with marketing, and then add more specific labels like online, mobile, and physical to different pages where required.

You could then use the Content by Label macro to display different combinations of pages with the marketing label. Some combinations you could use would be:

  • All pages with the label marketing.
  • Pages which have all of the following labels: marketing, mobile, and online.
  • Pages with either the mobile or online labels, in the Marketing space.

Alternatively, if you're working on a project across multiple teams, you can label everything to do with the project with that project name, and use a label to display all that content in one space. 

Below you'll find a list of macros that use labels in different ways. See which ones work best for you.

Content by Label macro

The Content by Label macro displays a list of content marked with specified labels.

Content Report Table macro

The Content Report Table macro displays a set of pages and blog posts in tabular format, based on the specified labels.

Labels List macro

The Labels List macro lists all labels of a space, grouped alphabetically.

Navigation Map macro

The Navigation Map macro renders the list of pages associated with a specified label as a navigation map.

Popular Labels macro

The Popular Labels macro displays popular labels in a word cloud.

Recently Used Labels macro

The Recently Used Labels macro lists labels most recently used in a specified scope - global (site), space, or personal.

Related Labels macro

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