Gallery Macro

Add the Gallery macro to a page to display a collection of images attached to this page, or other Confluence pages.

This macro is great for situations where you need to:

  • curate a collection of images that are attached to several different pages
  • display a set of images in a particular order, such as by date. 

One benefit of the Gallery macro over simply inserting images into a page is that it will automatically update when files are added or removed from the page. 

On this page:

Screenshot: Gallery macro on a page showing images from this page, with captions. 

The captions below the images are drawn from the comments on the attachments. For information about adding comments to attachments, see Upload Files.

For general information about working with files in Confluence, see Files

Add this macro to your page

To add the Gallery macro to a page:

  1. From the editor toolbar, choose Insert > Other Macros.
  2. Choose Gallery from the Media or Visuals & Imagery categories.
  3. Use the macro parameters below to specify the files you want to display.
  4. Choose Insert

You can then publish your page to see the macro in action. 

Screenshot: Entering parameters for the Gallery macro

Change the macro parameters

Macro parameters are used to change the behaviour of a macro.

To change the macro parameters:

  1. In the editor, click the macro placeholder and choose Edit.
  2. Update the parameters as required then choose Insert.

Here's a list of the parameters available in this macro. 

Parameter

Default

Description

Gallery Title
(title

Nothing

Specify a title for your gallery.

Number of Columns
(columns

4

Specify the number of columns for your table.

Images to Exclude
(exclude

No exclusions. Include all the pictures on the page.

The gallery will ignore any pictures specified. You can specify more than one picture, separated by commas.
Note: The filename and filetype for this parameter are case-sensitive. For example, 'my picture.PNG' will not be recognized as 'my picture.png'.

Include these Images Only
(include

Include all the pictures on the page.

If you specifically include one or more pictures, the gallery will show only those pictures. You can specify more than one picture, separated by commas.
Note: The filename and filetype for this parameter are case-sensitive. For example, 'my picture.PNG' will not be recognized as 'my picture.png'.

Exclude Images with these Labels
(excludeLabel

No exclusions. Include all the pictures on the page.

The gallery will ignore any pictures that have the specified label. You can specify more than one label, separated by commas. For information on labeling the attachments, see Add, Remove and Search for Labels.
Include Images with these Labels Only
(includeLabel
None. The images are not filtered by label.Filters the images to display, based on a list of labels. If you wish to enter more than one label, separate the labels with commas. Confluence will show only images that have all the labels specified. (The match is an AND, not an OR.) For information on labeling the attachments, see Add, Remove and Search for Labels.

Use Images in these Pages
(page

If no page is specified, the gallery macro displays the images attached to the page on which the macro is used.

Specify the title of the page which contains the images you want displayed. You can specify more than one page name, separated by commas. To specify a page in a different space, use the following syntax: SPACEKEY:Page Title

Sort Images By
(sort

None. The sort order is unspecified and therefore unpredictable.

Specify an attribute to sort the images by. Sort order is ascending, unless you select the Reverse Sort parameter (see below). Options are:

  • name – file name.
  • comment – comment linked to the attached file.
  • date – date/time last modified.
  • size – size of the attached file.

Reverse Sort
(reverse

Off. Sort order is ascending

Used in combination with the Sort Images By parameter above. Use Reverse Sort to reverse the sort order, from ascending to descending.

Available values in storage format and wikimarkup:

  • true – Sort order is descending.
  • false – Sort order is ascending.

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

If the name of an attached file or page contains a comma, you can refer to it in the relevant parameters below by enclosing it in single or double quotes, for example "this,that.jpg", theother.png

Image file formats

You can attach image files of any format to a page. Confluence supports the following image formats in the Gallery macro and when displaying an image on a page:
  • gif
  • jpeg
  • png
  • bmp (depending on browser support)

 

Other ways to add this macro

Add this macro as you type

Type followed by the start of the macro name, to see a list of macros. 

Add this macro using wiki markup

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

Macro name: gallery

Macro body: None.

{gallery:title=My holiday pictures|reverse=true|sort=size|page=My page1, ds:Welcome to Confluence|excludeLabel=badlabel1, badlabel2|columns=3|exclude=badpicture.png}
Last modified on Feb 21, 2023

Was this helpful?

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