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_-]+$`
`function`	`string`	Required if using UI Kit 1.	A reference to the function module that defines the module. Only used in UI Kit 1.
`resource`	`string`	Required if using custom UI or the current 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.
`resolver`	`{ function: string }` or `{ endpoint: string }`	Yes	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 (preview) to integrate with a remote back end.
`viewportSize`	`'small'`, `'medium'`, `'large'` or `'xlarge'`		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`	Yes	The title of the macro. In Confluence, this is displayed in the editor.
`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`		The description of the macro. In Confluence, this is displayed in the editor.
`config`	`{ function: string }`		Contains a `function` property, which references the `function` module that defines the macro configuration.
`export`	`{ function: string }`		Contains a `function` property, which references the `function` module that defines the export view of the macro. The Forge backend converts UI Kit to HTML for display in the given exportType. Note: This function also works for Custom UI macros, even though it is a UI Kit function.
`layout`	`'inline'`, `'block'`		Sets whether the macro is treated as a `block` or `inline` element in the editor. `'block'` type is used by default. Note: `'inline'` type works only for UI Kit macros

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

UI Kit

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.