This module now has support for UI Kit 2 (preview) for faster user experiences and to access additional React features.

For more information on all the supported modules, see the Supported products and their modules section.

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.

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`	The macro module requires either a `function` for usage with the UI kit, or a `resource` when building with custom UI.	A reference to the `function` module that defines the macro.
`resource`	`string`		A reference to the static `resources` entry that your macro wants to display. See resources for more details.
`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 (preview) to integrate with a remote back end. Can only be set if the module is using the `resource` property.
`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.
`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

Custom UI

Property	Type	Description
`type`	`string`	The type of the module (`macro`).

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.