• Products
  • Documentation
  • Resources

Insert the filter by label macro

The Filter by label macro is used to display lists of pages, blog posts or attachments that share a particular label or set of labels  It's great for collecting related pages together and filtering out content that you don't want to see.

For example, you could use this macro to display a list of all pages that have the label 'feature-shipped' and include the word 'Blueprint', or to list any pages with the label 'meeting-notes' that you've been mentioned in.

Here's how the list will look on your page:

See how the Content by Label macro presents pages with a certain label

To add a list of labeled content to your page: 

  1. From the editor, select from the toolbar or type / to bring up the insert menu.

  2. Find the Filter by label macro and select it. You can also type /filterbylabel to select this macro from the insert menu right in the body of your page.

  3. Upon selection, a modal will appear where you can customize and configure your list prior to inserting it.

To configure your list of labeled content:

  1. From the configuration modal, search and select the label(s) you want to use to filter your list via the Add label(s) field.

  2. You can then choose whether or not to filter this list even more by selecting Add filter(s).

  3. Finally, select More options to customize the list even further.

  4. When you’re done configuring your list, you can select Preview to see how it will look on your page.

  5. Select Insert to embed your configured list on your page.

The items in this list are dynamic — if additional updates take place, they'll automatically be reflected in the list.

To edit an existing list of labeled content:

  1. While editing your page, select the Filter by label macro you want to re-configure.

  2. Select the Edit () icon to open the configuration modal.

  3. Adjust the parameters of your list of labeled content.

  4. Select Insert to finalize the changes to your list.

You can also select the centered, medium-width, or full-width icon to adjust the width of your list. Select the copy icon to duplicate it elsewhere, and/or the trashcan icon to remove it entirely.

What CQL filters are available to use?

CQL (Confluence Query Language) was developed by Confluence for use in certain macros and Confluence search. It allows you to add as many filters as you need to narrow down search results.

By selecting Add filter(s) in the configuration modal, you can use the following CQL filters:






Returns pages, blog posts or attachments with these labels.

OR (multiple values in the same filter)

AND (multiple Label filters)


Returns items that contain this text in the title.

CONTAINS (single word or phrase)


Returns only pages, blogs or attachments.

OR (multiple values in the same filter)


Returns items that contain this text.

CONTAINS (single word or phrase)

Date created

Returns items created on this date.

CONTAINS (single word or phrase)

Last modified

Returns items last updated on this date.

CONTAINS (single word or phrase)


Returns items created by these people.

OR (multiple values in the same filter)


Returns pages or blog posts that were created or edited by these people.

OR (multiple values in the same filter)

Mentioned user

Returns pages and blog posts that @mention these people.

OR (multiple values in the same filter)


Returns items from these spaces.

OR (multiple values in the same filter)

Child pages

Returns only direct children of this page (further sub-pages won't be included)

EQUALS (one page only)

All subpages

Returns all pages that live under this page in the page tree.

OR (multiple values in the same filter)


AND, OR, and NOT operators

  • For an OR search, specify multiple values in the same field.
    So to show pages with 'label-a', 'label-b' or both you'd put 'label-a' and 'label-b' in the same Label field, like this:

Example of selecting multiple labels to create a search with an OR operator
  • For an AND search, add more than one filter and specify a single value in each.
    To show only pages with label-a and label-b you'd put 'label-a' in one label field, then add a second Label field to the macro, and put 'label-b' in the second one, like this:

Example of searching for labels using an AND operator

Put simply, OR values are entered in the same filter, AND values are entered in different filter. 
Only some filters support AND. If the filter doesn't support the AND operator, you won't be able to add that filter more than once.  

  • For a NOT search, enter a minus sign (-) before the label. This'll exclude everything with that label.

More options

The following configuration options control how your list appears on the page:




List title


Display an optional title header for your list

Sort order

CQL relevancy

This dropdown allows you to configure the order of your list.

  • Title - displays items alphabetically by title, or reversed.

  • Created - displays items in order from most recently created to least, or vice versa.

  • Modified - displays items in order from most recently updated to least, or vice versa.

Display preview


This dropdown allows you to display your list with or without a preview of each child page’s content.

  • Page preview - displays a snapshot of the top section of a page’s content, including formatted text, images, and certain macros.

  • Excerpt preview - displays the first line of text contained in an Excerpt macro on any listed child pages. If there isn’t an excerpt on the page, nothing will be shown.

Display full list


Check to display all items in your list at once, or un-check to manually customize how many items to display.

Max number in list


When the Display full list box is unchecked, this input field allows you to enter the number of items you want to display in your list. This can be any value up to 500.

Display labels


Check to display, or un-check to hide, the labels applied to each item.

Display space name


Check to display, or un-check to hide, the space name associated with each item.

Wiki markup example

Wiki markup is only supported in the legacy editor.

Wiki markup is useful when you need to add a macro outside the editor, for example as custom content in the sidebar, header or footer of a space.

Macro name: recently-updated

Macro body: None.

1 {recently-updated:spaces=ds|author=admin|max=10|hideHeading=true|width=50%|theme=sidebar|showProfilePic=true|labels=choc|types=page}


Additional Help