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.

For UI Kit 1, see the Macro component documentation for more information.

On apps that use Custom UI, module content is displayed inside a special Forge iframe which has the sandbox attribute configured. This means that HTML links (for example, <a href="https://domain.tld/path">...</a>) in this iframe won't be clickable. To make them clickable, use the router.navigate API from the @forge/bridge package.

Example of a macro

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.
`function`	`string`	Deprecated Required if using UI Kit 1	The key of a function module that returns a UI Kit 1 component.
`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'`, `'xlarge'` or `'max'`		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.
`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 and is available to participants of the Internationalization for Forge EAP. 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 and is available to participants of the Internationalization for Forge EAP. See i18n object.
`config`	`boolean`, `{ function: string }` or `config object`		Set `config` to `true` if you are using classic macro configuration. Set `config` with the `function` property if you are using a UI Kit 1 macro. Set `config` to the config object if you are using a custom macro configuration.
`export`	`{ function: string }`		For UI Kit 1 and Custom UI use only. Contains a `function` property, which references the `function` module that defines the export view of the macro, specified in UI Kit 1 components. The specified function can consume the exportType from the extension context in order to specify different export views per export type.
`adfExport`	`{ function: string }`		For UI Kit and Custom UI use only. Contains a `function` property, which references the `function` module that defines the export view of the macro, specified 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.
`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. A limitation exists for custom UI apps that prevents inline macros from dynamically resizing when the content of the macro is changed. `'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.

i18n object

Internationalization (i18n) for Forge apps is now available through Forge's Early Access Program (EAP). For details on how to sign up for the EAP, see the changelog announcement.

EAPs are offered to selected users for testing and feedback purposes. APIs and features under EAP are unsupported and subject to change without notice. APIs and features under EAP are not recommended for use in production environments.

For more details, see Forge EAP, Preview, and GA.

Key	Type	Required	Description
`i18n`	`string`	Yes	A key referencing a translated string in the translation files. For more details, see Translations.

Config object

Key	Type	Required	Description
`title`	`string` or `i18n object`	No	A title for the 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.
`render`	`'native'`	Yes for UI Kit	Indicates the module uses UI Kit.
`viewportSize`	`'small'`, `'medium'`, `'large'`, `'xlarge'` or `'max'`		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.

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

UI Kit 1

Property	Type	Description
`type`	`string`	The type of the module (`macro`).
`exportType`	`string`	The type of the current export. Available for the `export` function only. Valid values: One of `pdf`, `email`, `word` or `other`. Note: `other` implies export other than pdf, email or word. For example, when the macro is shown in the Page history or exported via API.

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

Tutorial

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