Add, Remove and Search for Labels

Labels are key words or tags that you can add to pages, blog posts and attachments. You can define your own labels and use them to categorize, identify or bookmark content in Confluence. 

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.

Because labels are user-defined, you can add any word that helps you identify the content in your site.

You can also apply labels (known as categories) to spaces, to help organize your Confluence spaces. See Use Labels to Categorize Spaces.

Label a page or blog post

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 or blog post:

  1. At the bottom of the page, choose Edit labels  or hit L on your keyboard
  2. Type in a new label (existing labels are suggested as you type)
  3. Choose Add

If you're editing or creating a page, and you want to add labels, choose the Edit label icon at the top of the page.

Labels can't contain spaces, are lower case, and can contain a maximum of 255 characters. You can add multiple labels by adding a space between each label, any capitals will be automatically converted to lower case. If you want a label to include more than one word, use an underscore or hyphen (the only two special characters that labels accept). For example this_is_a_label or this-is-a-label.

Label an attachment

  1. Do either of the following:
    • Go to the page that contains the attachment and choose 

      Error rendering macro 'excerpt-include'

      User 'null' does not have permission to view the page.

    • Go to the space and choose  Space tools > Content Tools from the bottom of the sidebar, then choose Attachments
    You'll see a list of attachments, with any existing labels listed in the Labels column.
  2. Choose the Edit label icon  beside the list of labels and type in a new label (existing labels are suggested as you type)
  3. Choose Add

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

(info) If you add one or more labels to a template, that label will be copied to the page when someone adds a page based on that template. See Creating a Template.

The Labeled content page

If you're viewing a page or post that has labels or displays the Attachments macro, you can choose any label to go to the Labeled content page for the space. Choose Popular Labels or All Labels from the cog at the top-right – to view the most-used labels or all labels in the space – or choose See content from all spaces from the cog to view labeled content from all spaces in your Confluence site.

Screenshot: The Labeled content page

The Popular Labels option displays a word cloud, where the bigger a label is displayed, the more popular it is. Choose any label to view content tagged with that label. 

You can also navigate to the labels view for a space by entering the following URL (replace SPACEKEY with the space's key):


Search by label

You can use the ' labelText: ' prefix to search specifically 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

Entering a URL with an appended label or labels is another way to search for pages with particular labels.

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

The Labeled content page will load, showing search results for pages with the both labels, 'foo' and 'bar'. Replace 'foo' and 'bar' with the label(s) you want to search for, and separate multiple labels with a + symbol.

Adding a label to your results:

Once you're on the Labeled content page, you can add more labels to your search by choosing them from the Related Labels list at the top-right of the page. Each label is listed with a plus (+) sign.

If you want to remove labels from your search, locate the included labels at the top of the page and choose the label(s) you want to remove. Each included label will be listed with a minus (–) sign.

Remove labels

When viewing page, blog post, or attachment labels, an x appears alongside each label. Choose the x to remove the label.

You can't remove, consolidate or manage labels directly. A label is created by adding it to a page for the first time, and ceases to exist once it's been removed from all pages it was added to.

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.

If you are using the Labels List Macro, the appearance of labels from deleted pages is considered a bug. Track the issue at  CONFSERVER-55441 - Getting issue details... STATUS

Last modified on Mar 6, 2023

Was this helpful?

Provide feedback about this article
Powered by Confluence and Scroll Viewport.