Macro

The macro module inserts dynamic content into the user interface via an editor. Editor macros are only compatible with the Atlassian editor. All cloud sites use the Atlassian editor by default.

The macro module works in Confluence, where the macro is inserted by typing / and selecting from the quick insert menu of the editor. The macro module is implemented by a Forge function.

Manifest structure

1
2
modules {}
└─ macro []
   ├─ key (string) [Mandatory]
   ├─ resource (string) [Mandatory]
   ├─ render (string) [Optional]
   ├─ resolver {} [Optional]
   ├─ viewportSize (string) [Optional]
   ├─ title (string | i18n) [Mandatory]
   ├─ icon (string) [Optional]
   ├─ categories (string[]) [Optional]
   ├─ unlicesedAccess (List<string>) [Optional]
   ├─ description (string | i18n) [Optional]
   ├─ hidden (boolean) [Optional]
   └─ config (boolean | {} | config object) [Optional]
     ├─ icon (string) [Optional]
     ├─ title (string | i18n) [Optional]
     ├─ resource (string) [Mandatory]
     ├─ render (string) [Optional]
     ├─ viewportSize (string) [Optional]
     └─ openOnInsert (boolean) [Optional]
   ├─ adfExport {} [Optional]
   ├─ layout (string) [Optional]
   └─ autoConvert [] [Optional]
     └─ matchers [] [Mandatory]
        └─ pattern (string) [Mandatory]

resources []
├─ key (string) [Mandatory]
└─ path (string) [Mandatory]

Properties

Property
Type
Required
Description
key
string
Yes

A key for the module, which other modules can refer to. Must be unique within the manifest.
Regex: ^[a-zA-Z0-9_-]+$
resource
string
If using Custom UI or modern versions of UI Kit
The key of a static resources entry that your module will display. See resources for more details.
render
'native'
If using modern versions of UI Kit
Indicates the module uses UI Kit.
resolver
{ function: string } or
{ endpoint: string }

Set the function property if you are using a hosted function module for your resolver.
Set the endpoint property if you are using Forge Remote to integrate with a remote back end.
viewportSize
'small', 'medium', 'large' or 'xlarge'

Use viewportSize to pre-reserve the height in the editor before the app loads. Setting this prop disables auto-resizing. This is only supported for the main macro in Custom UI apps.
title
string or i18n object
Yes

The title of the macro. In Confluence, this is displayed in the editor.
The i18n object allows for translation. See i18n object.
icon
string

The icon displayed next to the title.


For Custom UI and UI Kit apps, the icon property accepts a relative path from a
declared resource. Alternatively, you can also use an absolute URL to a self-hosted icon. See
Icons for more information.
If no icon is provided, or if there's an issue preventing the icon from loading, a
generic app icon will be displayed.
categories
string[]
The categories of the macro. In Confluence, this is used for categorisation in the macro browser.



formatting
confluence-content
media
visuals
navigation
external-content
communication
reporting
admin
development

description
string or i18n object

The description of the macro. In Confluence, this is displayed in the editor.
The i18n object allows for translation. See i18n object.
hidden
boolean

Defaults to false. When set to true, hides the macro from the quick insert menu and macro browser in Confluence. This prevents users from inserting new instances of the macro through these interfaces.
Existing macros on pages continue to render normally, even when this property is set to true.
config
boolean, { function: string }, { openOnInsert: boolean } or config object

Set config to true if you are using classic macro configuration without needing openOnInsert.
Set config with the openOnInsert property if you are using classic macro configuration and need the openOnInsert feature. openOnInsert defaults to false.
Set config to the config object if you are using a custom macro configuration.

config.icon
string

The icon displayed next to the title in the custom config modal.


For Custom UI and UI Kit apps, the icon property accepts a relative path from a
declared resource. Alternatively, you can also use an absolute URL to a self-hosted icon. See
Icons for more information.
If no icon is provided, or if there's an issue preventing the icon from loading, a
generic app icon will be displayed.
config.title
string or i18n object
A title for the config. If the viewport size is fullscreen*, then the title rendered in the modal header will be this title.
config.resource
string
Required if using Custom UI or the latest version of UI Kit.
A reference to the static resources entry that your context menu app wants to display. See resources for more details.
config.render
'native'
Yes for UI Kit
Indicates the module uses UI Kit.
config.viewportSize
'small', 'medium', 'large', 'xlarge', 'max' or 'fullscreen'
The display size of resource. Can only be set if the module is using the resource property. Remove this property to enable automatic resizing of the module. For fullscreen viewports, the config.title and config.icon will be displayed in the header. Supported in both UI Kit and Custom UI.
config.openOnInsert
boolean
Defaults to false for classic configuration, defaults to true for custom configuration. An optional configuration to control if the classic configuration sidepanel or the custom configuration modal is automatically opened when first inserted.
adfExport
{ function: string }

Defines how your macro appears when a Confluence page is exported.
Contains a function property which references a function module that returns the macro content in Atlassian document format.
The specified function can consume the exportType directly from the function's
payload in order to specify different views per export type. The exportType can be one of
pdf, word, or other. See this tutorial for more information.
 

The adfExport function is invoked once per macro instance during export operations. Pages with many macro instances can trigger a large number of invocations in a single export, potentially causing rate limiting and performance issues. Consider minimizing backend work within the function and informing customers about potential limitations when using many macros on pages that will be exported.
 
layout
'block', 'inline' or 'bodied'

'block' type is used by default.

'inline' shows the element inline with existing text.

For UI Kit apps, inline macros dynamically resize to wrap the content.
Custom UI inline macros have a minimum rendered width of approximately 300px due to the browser's default iframe sizing. To allow your macro to render at a smaller width, set width: fit-content on the body element of your Custom UI app's HTML. See Notes on layout and sizing for details.



'bodied' sets the macro to have a rich text body.

This allows users to insert and edit rich content (such as images and tables) within the macro using the Confluence editor, and allows your app to insert a body using a custom editor.
Please see the link to the tutorial here.


autoConvert
autoConvert object

Inserts a macro into the editor when a recognised URL is pasted in by the user.
See Macro autoconvert.
autoConvert.matchers
[matcher, ...]
Yes, if using autoConvert
The list of patterns that define what URLs should be matched.
autoConvert.matchers.pattern
string
Yes, if using autoConvert

A string that defines a specific URL pattern to be matched, using wildcards for variable
parts of the URL, such as unique IDs.

Use multiple wildcards to match multiple sub-paths. Do not include all sub-paths with a single wildcard.
Ensure URLs do not contain whitespace unless it is URL encoded.
Wildcards cannot be used in place of a protocol. Custom URL Schemes are supported See examples
Maximum length of the pattern is 1024 characters.

emitsReadyEvent
boolean
No
Defaults to false. An optional configuration to notify Confluence that the macro will send a emitReadyEvent when it has completed loading and is ready for export or further processing. This should be used with view.emitReadyEvent(). See the view bridge function for more information.
unlicensedAccess
List<string>

A list of unlicensed user types that can access this module. Valid values are: unlicensed (Guests Users), and anonymous. For more information, see
Access to Forge apps for unlicensed Confluence users.

i18n object
Key
Type
Required
Description
i18n
string
Yes
A key referencing a translated string in the translation files. For more details, see Translations.
Dynamic module (Preview)
This module can also be declared as a dynamic module. However, this capability is currently
available as a Forge preview feature.
For more details, see Dynamic Modules.
When you register a dynamic macro module, the data object uses the same properties as a static macro module in the manifest. The module key is generated server-side and returned in the create response; for updates, supply it in the URL path.
Code examples
The following examples show Dynamic Module implementations specific to this module. For more detailed information about the API used in these examples
(including error handling information), see Dynamic Modules API.
Create a dynamic macro module
Forge
Node.js
1
2
import { asApp } from "@forge/api";
const payload = {
  "type": "macro",
  "data": {
    "resolver": {
      "function": "resolver"
    },
    "resource": "main",
    "render": "native",
    "title": "Dynamic macro",
    "description": "A macro registered with the Dynamic Modules API",
    "autoConvert": {
      "matchers": [
        {
          "pattern": "https://www.example.com/*/about"
        }
      ]
    }
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/dynamic/module/`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify(payload),
});
const body = await response.text();
console.log(`Response: ${response.status} ${body}`);
Update a dynamic macro module
Forge
Node.js
1
2
import { asApp } from "@forge/api";
const key = "macro-dynamic";
const payload = {
  "type": "macro",
  "data": {
    "resolver": {
      "function": "resolver"
    },
    "resource": "main",
    "render": "native",
    "title": "Updated dynamic macro",
    "description": "A macro updated with the Dynamic Modules API",
    "autoConvert": {
      "matchers": [
        {
          "pattern": "https://www.example.com/*/about"
        },
        {
          "pattern": "https://www.example.com/*/music"
        }
      ]
    }
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/dynamic/module/${key}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'PUT',
  body: JSON.stringify(payload)
});
const body = await response.text();
console.log(`Response: ${response.status} ${body}`);
 

When you update the URL patterns for a dynamic macro module's autoconvert matchers, you may need to leave the Confluence editor, perform a hard refresh on the Confluence page view, and then re-open the editor before the updated patterns are applied.
 
Extension context
UI Kit and Custom UI
Property
Type
Description
type
string
The type of the module (macro).
content.id
string
A string that represents the unique identifier of the content object.
content.type
"page", "blogpost" or "space"
A string that represents the type of the content object.
content.subtype
string or null
A string that represents the subtype of the content object. null is returned if subtype does not apply.
space.id
string
A string that represents the unique identifier of the space object.
space.key
string
A string that represents the unique key of the space object.
isEditing
boolean
Indicates whether the macro is opened in the editor or not.
references
ReferenceEntity[]
An array of reference entities (if any). Reference entities are a list of any other ADF nodes on the page that are referenced by this macro.
config
object
The configuration parameters saved in this macro.
macro.body
ADF document
The rich text body of the macro. Available for layout: bodied macros only.
autoConvertLink
string
The link pasted by a user that has matched an AutoConvert app.
template.id
string
A string that represents the unique identifier of the template. This value is only available when the macro is in a saved template.
Macro autoconvert
Macro autoconvert allows your app to automatically insert a macro into the editor when a user pastes
a recognized URL. This is achieved by defining URL patterns in the manifest using the matchers
property. These matchersare registered in the editor when the app is installed.
Example
1
2
modules:
  macro:
    - key: autoconvert-app
      resource: main
      render: native
      resolver:
        function: resolver
      title: Forge app for autoconvert
      description: Example for autoconvert manifest
      autoConvert:
        matchers:
          - pattern: https://www.example.com/*/about
          - pattern: https://www.example.com/*/music
          - pattern: https://*.example.com/*/movies/*
          - pattern: https://example.com/gifs/*/
          - pattern: http://*.example.com/media/*/.gif
          - pattern: customScheme:\\example:custom
          - pattern: customScheme:example:*
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: "<your app id>"

The URL patterns use wildcards to match parts of the URL that can vary, such as unique IDs. Wildcards are
defined using *.
Use a new * for each segment in the URL you want a wildcard for. For example, https://www.example.com/* will match https://www.example.com/about but will not match https://www.example.com/about/contact. To match this path as well you need to include https://www.example.com/*/* as one of your matchers.
You'll need to define a separate matcher for each relevant internet protocol, such as http and https.
Creating custom URL schemes is also supported. For example, customScheme:* can be used to match any URL that starts with that custom scheme such ascustomScheme:\\example:custom. Any custom schemes will have to be registered on the system they will be used on, such as iOS, Windows or Android. Either :\\ or just : can be used as the initial separator in the URL scheme then : thereon.
Example patterns
Wildcard path
1
2
- "pattern": "https://www.example.com/*/about"

Wildcard in subdomain
1
2
- "pattern": "https://www.*.example.com/help"

Matching wildcard paths
1
2
- "pattern": "https://bitbucket.org/*/*/*"

Matching custom URL schemes
1
2
- "pattern": "customScheme:example:custom"
- "pattern": "customScheme:\\example:custom"

Matching custom URL scheme wildcard
1
2
- "pattern": "customScheme:example:*"
- "pattern": "customScheme:\\example:*"

When a pasted URL matches a defined pattern, the macro is created in the editor, and the URL is
captured and inserted as a parameter into the macro body. This parameter can be accessed using the
autoConvertLink property.
Example app: Macro autoconvert for UI Kit
Learn how to configure auto convert in your manifest.yml file, including pattern matching and setting permissions for API calls.
See example app
Macro custom configuration
Extension context in the macro editor
There are two additional extension context parameters available when you are in macro configuration editor context.
Parameter
Type
Details
macro.isConfiguring
boolean
true if the currently rendered resource is the config resource, false if it is the macro's default resource
macro.isInserting
boolean
true if a new macro is being inserted, false if an existing macro is being edited
Options for submitting the configuration
This table details the options supported by view.submit()
in the context of custom macro configuration.
Parameter
Type
Required
Details
Code
config
Config payload
Yes
Sets the config properties of the macro.

1
2
view.submit({
  config: {
    param1: "test",
    param2: [1, 2, 3]
  }
})
        
body
ADF document
No
Sets the rich text body of the macro. Can only be used with layout: bodied macros.

1
2
view.submit({
  config: {},
  body: {
    type: "doc",
    version: 1,
    content: [
      // ADF content
    ]
  }
})
        
keepEditing
boolean
No
Defaults to false, which automatically closes the config modal on submit. Set this to true to keep the modal open.

1
2
view.submit({
  config: {},
  keepEditing: true
})
        
Supported config payload format
The config payload only supports values that can be serialised to JSON.
The following types are allowed on the payload:

undefined
string
number
boolean
object (can contain any of the allowed types, including nested objects)
array (can contain strings, numbers, booleans, and objects; all items in the array must be of the same type).

The following types are not allowed:

Nested arrays (arrays as direct children of arrays)
null
Any data types that are not serializable to JSON (e.g. Map, Set, etc.)

If you want greater control over the storage format of your configuration, such as being able to store nested arrays and nulls, we recommend serializing your configuration to JSON upfront, and storing it as a string.
Error code guide
This table details the possible error codes that may be thrown by view.submit():
Error code
Details
INVALID_PAYLOAD
The top-level parameter passed to view.submit() must be an object.
INVALID_CONFIG
The config prop provided must be an object that is compliant with the config payload format above.
INVALID_EXTENSION_TYPE
When providing a body, the macro must be a rich text macro (layout: "bodied").
INVALID_BODY
The provided body is not a valid ADF document node.
MACRO_NOT_FOUND
The macro that you are attempting to update no longer exists. It may have been deleted by another user editing the page.
Notes on layout and sizing
Inline macro width (Custom UI)
Custom UI inline macros are rendered inside an <iframe>. All major browsers apply a default minimum width of 300px to <iframe> elements, which means your inline macro will render at a minimum of approximately 300px wide even if the content inside is smaller.
To override this and allow the macro to shrink to fit its content, add the following CSS to your Custom UI app. The recommended approach is to add it in a <style> tag or an external stylesheet in your index.html:
1
2
<style>
  body {
    width: fit-content;
  }
</style>

This tells the browser to size the body to its content rather than expanding to the iframe default width. The fit-content value is supported across all browsers that Forge targets.
 

If you apply these styles using a style attribute directly on the <body> element (for example, <body style="width: fit-content">), you must also declare the unsafe-inline permission in your manifest.yml, as inline styles are blocked by the default Content Security Policy:
1
2
permissions:
  content:
    styles:
      - "unsafe-inline"

Using a <style> tag or external stylesheet does not require this permission.
 
 

This limitation only applies to Custom UI apps. UI Kit inline macros automatically resize to wrap their content without any additional configuration.
 
Tutorials


Add configuration to a macro with UI Kit
The app allows you to customize what the macro displays by adjusting settings in a form.
Start tutorial







Add custom configuration to a macro
The app’s configuration can be edited using a custom configuration modal.
Start tutorial







Using rich-text bodied macros
How to configure the manifest and render rich text body content.
Start tutorial




Rate this page:
Unusable
Poor
Okay
Good
Excellent