Last updated May 23, 2024

Connect macros


What is a macro?

A macro is a type of Connect module that inserts dynamic content inside a Confluence page. You can use macros to display data from other systems, create specialized content such as diagrams or mathematical symbols, or display content contained within the macro itself.

You can use macros to build the following types of apps:


Macros enable you to integrate other systems into Confluence, either your own services or others that are available via APIs. Your macro may integrate aspects of a service's experience within a Confluence page, or create an experience that accesses the service's API.

Examples include integration with:

  • An external diagramming service to display and edit diagrams
  • An external HR system to display candidate details
  • A social media API to display related activity

Specialized content

You can use macros to create content that meets a specialized use case. This could be content that's difficult or impossible for users to create using default types of content available in the Confluence editor.

Examples include:

  • Adding specialized mathematical symbols and equations
  • Composing diagrams that are stored as attachments
  • Displaying a software roadmap with an editor for adding and editing colored bars

Composed content

Macros can display content contained within the macro itself, known as the 'macro body'. For example, the chart macro that's built into Confluence uses data in a table in the macro body to display a chart. In the editor, Confluence renders the macro as a container where users can add data for the macro to display.

Examples include:

  • Displaying a chart based on data in a contained table
  • Displaying a carousel of images in the macro body
  • Hiding and showing contained content using a toggle (as in the Confluence expand macro)

Building macros

You specify the parameters for a macro by adding either of the following elements to the app descriptor:

We recommend dynamic macros in most cases, as asynchronous rendering won't negatively impact the loading of the rest of the page.

Macro view

Macros need to render within pages in order to be viewed. This is an easy first step to take after defining your macro following the getting started guide or the technical documentation. The tutorials show examples of how to use Handlebars to create views, but you can use whatever templating engine you like.

Macro create

When creating your macro you need to decide between a dynamic macro and a static macro. Dynamic macros are rendered asynchronously within an iframe. Static macros are rendered synchronously.

We recommend dynamic macros by default, as they don't negatively impact page load time for users.

When your macro is defined, default Confluence features will allow users to create instances of your macro on a page using the macro browser and related keyboard shortcuts.

If you are integrating an external service with a unique URL pattern, you may want to consider implementing an autoconvert extension also which dynamically matches the URL when pasting and converts it to a macro instance.

Macro edit

When users add your macro to a page, there are three ways they can edit and specify properties for it:

  • Default editor based on macro properties - Confluence will display the standard macro properties dialog, which allows users to specify values for your macro's properties. This is the quickest approach.
  • Custom macro editor - You design the experience for editing your macro's properties based on our design guidelines.
  • Full screen designer - Useful when a full screen experience is required for complex tasks, like diagram editing. Take a look at our design guidelines for previewing and full screen editing.

The property panel can also be extended to provide a shortcut to changing macro properties.

Let's do this!

Get going by following these tutorials:


Rate this page: