• Products
  • Documentation
  • Resources

Insert the attachments macro

The Attachments macro displays a list of files attached to a page.  

It also allows users (with appropriate permissions) to:

  • upload a file to the page, directly from the list 

  • edit attachment properties and labels

  • delete an attached file (this deletes all versions of the file)

  • preview image attachments

  • edit attached Office and PDF documents using the Office Connector.

  • download all files attached to the page. 

You can use the macro parameters to turn off previews if you have very large attachments. 

Use the Attachments macro

To add the Attachments macro:

  1. When editing, select from the toolbar

  2. Find the macro by name and select it

  3. Configure it as needed

You can also type / on the page to bring up the same list you'd see by selecting from the toolbar. Continue typing the name of the macro to filter the list.

To edit the Attachments macro:

  1. Select the macro placeholder.

  2. Select the Edit icon to open the configuration panel.

  3. Configure the parameters. Your changes are saved as you go.

  4. Resume editing the page, and the panel closes.

You can also select the centered , medium-width , and full-width icons to adjust the width of some macros. Select the trashcan iconto remove the macro.


Parameters are options that you can set to control what and how content from the macro appears on the page. 

If the parameter name used in Confluence Cloud storage format or wikimarkup is different than the label used when inserting macros using the browser or the slash command, it will be listed below in brackets (example).




Filename Patterns(patterns)


A comma-separated list of regular expressions, used to filter the attachments by file name. Note that the parameter values must be regular expressions. For example:

  • To match a file suffix of 'jpg', use .*jpg (not *.jpg).

  • To match file names ending in 'jpg' or 'png', use .*jpg,.*png


Attachment Labels(labels)


A list of labels, used to filter the attachments to display. If you wish to enter more than one label, separate the labels with commas. Confluence will show only attachments that have all the labels specified. (The match is an AND, not an OR.) For information on labeling the attachments, see Use labels to organize pages and attachments.

Include Old Attachment Versions(old)


A value of true will include previous attachment versions in the list.

Sort By(sortBy) 


The sort order for attachments. Note that people viewing the page can change the sort order by clicking the column headings. Valid values are:

  • date – sorts by updated date in reverse chronological order (newest first)

  • size – sorts largest to smallest

  • name – sorts alphabetically

  • created date - sorts by creation date in reverse chronological order (newest first)

Sort Order(sortOrder) 


Used in combination with the Sort By parameter, to sort the attachments in ascending or descending order.

Allow Upload(upload) 


If selected, the list of attachments will include options allowing users to browse for, and attach, new files.

Page Title(page) 


Used to display attachments from another page. If you do not enter a page title, the macro will display the files attached to the current page.

Show Previews(preview) 


Used to display a preview of the attached file. If true, preview will be visible when the list item is expanded.

Number of items to display


Number of items to display per page of results.


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: attachments

Macro body: None.

1 2 3 4 {attachments:old=false|patterns=.*png,.*jpg|sortby=name|page=My page about chocolate|sortorder=descending|labels=chocolate,cookies|upload=false|preview=false}


Still need help?

The Atlassian Community is here for you.