view

The view object refers to the context in which a resource is loaded. For example, a modal.

close

The close method enables you to request the closure of the current view. For example, close a modal.

Function signature

1
2
function close(): Promise<void>;

Example

1
2
import { view } from "@forge/bridge";

view.close();

onClose

The onClose method enables you to register a callback that runs when a module-level modal is closed, such as the macro custom config modal.

For @forge/bridge modal and the UI Kit Modal component, we recommend using the inbuilt onClose prop instead.

Function signature

1
2
function onClose(payload: () => Promise<void>): Promise<void>;

Example

1
2
import { view } from "@forge/bridge";

view.onClose(async () => save());

submit

The submit method enables you to request form submission on the Jira custom field edit, Jira custom field type edit, and Jira context configuration views.

The submit method throws an error if the submission fails.

Function signature

1
2
function submit(payload: mixed): Promise<void>;

Where the payload shape is defined by the requirements of the views.

Example

This example shows how to request form submission on a Jira custom field edit.

1
2
import { view } from "@forge/bridge";

const onSubmit = async () => {
  const fieldValue = "new-value";
  try {
    return await view.submit(fieldValue);
  } catch (e) {
    // Handle the error
  }
};

getContext

The getContext method enables you to retrieve contextual information for your Custom UI app.

Function signature

1
2
function getContext(): Promise<Context>;

interface Context {
  accountId?: string;
  cloudId?: string;
  extension: ExtensionData;
  license?: LicenseDetails;
  localId: string;
  locale: string;
  moduleKey: string;
  siteUrl: string;
  timezone: string;
}

interface ExtensionData {
  [k: string]: any;
}

interface LicenseDetails {
  active: boolean;
  billingPeriod: string;
  ccpEntitlementId: string;
  ccpEntitlementSlug: string;
  isEvaluation: boolean;
  subscriptionEndDate: string | null;
  supportEntitlementNumber: string | null;
  trialEndDate: string | null;
  type: string;
}

Returns

• Context: An object containing contextual information about the current environment in which the app is running. The data available depends on the module in which your app is used.

  • accountId: The Atlassian ID of the user that interacted with the app.
  • cloudId: The ID identifying the cloud context of this app installation.
  • extension: Provides information related to the Forge app extension point, such as the content ID of the page where the app is running, module type and so on.
  • license: Contains information about the license of the app. Note: this field is only present for paid apps in the production environment. license is undefined for free apps, apps not listed on the Atlassian Marketplace, and apps in development and staging environments. See the LicenseDetails type for what information is available.
  • localId: A unique ID for this instance of this app in the content.
  • locale: The locale of the user that interacted with the app.
  • moduleKey: The key for the module as defined in the manifest.yml file.
  • siteUrl: The URL of the site of this app installation (e.g. https://example.atlassian.net).
  • timezone: The timezone of the user that interacted with the app.

Example

1
2
import { view } from "@forge/bridge";

const context = await view.getContext();

createHistory

The createHistory method enables your UI Kit and Custom UI app to manipulate the current page URL for routing within full page apps.

When using this API, the path and location properties are always relative to your app's URL.

The createHistory method is only available in the following modules:

• Bitbucket project settings menu page
• Bitbucket repository main menu page
• Bitbucket repository settings menu page
• Bitbucket workspace global page
• Bitbucket workspace personal settings page
• Bitbucket workspace settings menu page
• Compass admin page
• Compass component page
• Compass global page
• Confluence global page
• Confluence global settings
• Confluence space page
• Confluence space settings
• Jira admin page
• Jira global page
• Jira project page
• Jira project settings page

Learn how to add routing to a full page app with React Router.

Function signature

1
2
type LocationDescriptor = {
  pathname: string;
  search?: string;
  hash?: string;
  state?: any;
};
type UnlistenCallback = () => void;
type Action = "POP" | "PUSH" | "REPLACE";

function createHistory(): Promise<{
  action: Action;
  location: LocationDescriptor;
  push(path: string, state?: any): void;
  push(location: LocationDescriptor): void;
  replace(path: string, state?: any): void;
  replace(location: LocationDescriptor): void;
  go(n: number): void;
  goBack(): void;
  goForward(): void;
  listen(
    listener: (location: LocationDescriptor, action: Action) => void
  ): UnlistenCallback;
}>;

Example

1
2
import { view } from "@forge/bridge";

const history = await view.createHistory();

// e.g. URL begins as http://example.atlassian.net/example/apps/abc/123

history.push("/page-1");
// this updates the URL to http://example.atlassian.net/example/apps/abc/123/page-1

history.push("/page-2");
// this updates the URL to http://example.atlassian.net/example/apps/abc/123/page-2

history.go(-2);
// this updates the URL to http://example.atlassian.net/example/apps/abc/123

refresh

The refresh method enables you to fetch the data for the parent page again, without performing a full-page reload.

At the moment, it can be used by the following modules:

• Jira issue action
• Jira issue activity
• Jira issue glance
• Jira issue context
• Jira issue panel

Function signature

1
2
function refresh(): Promise<void>;

Example

1
2
import { view } from "@forge/bridge";

view.refresh();

theme

The theme object includes the method to enable theming. View the Design Tokens and Theming page for more details.

enable

The theme.enable method enables theming in the Forge app. This will fetch the current active theme from the host environment (e.g. Jira) and apply it in your app. It will also reactively apply theme changes that occur in the host environment so that your app and the host are always in sync.

Function signature

1
2
function enable(): Promise<void>;

Example

1
2
import { view } from "@forge/bridge";

await view.theme.enable();

1
2
// Example usage in a React app
// Make sure to call enable() before the app is mounted for tokens to be available before the first render
view.theme.enable().then(() => {
  ReactDOM.render(
    <React.StrictMode>
      <App />
    </React.StrictMode>,
    document.getElementById("root")
  );
});

changeWindowTitle

The changeWindowTitle method enables you to change the title of the current document in the following Jira modules: global page, admin page, project settings page, and project page.

Function signature

1
2
function changeWindowTitle(newTitle: string): Promise<void>;

Example

1
2
import { view } from "@forge/bridge";

await view.changeWindowTitle("New title");

emitReadyEvent

The emitReadyEvent function notifies Confluence that a Forge macro has completed loading and is ready for export or further processing. This enables Confluence or other consumers, such as our PDF export service, to reliably detect when macros are fully loaded, rather than relying on DOM scanning or timing heuristics.

This function is part of the @forge/bridge library and leverages the Forge Events API to emit an EXTENSION_READY event, including contextual information about the macro or extension that triggered it.

Function signature

1
2
function emitReadyEvent(): Promise<void>;

Example

1
2
import { view } from "@forge/bridge";
import { useEffect, useState } from "react";

const MyMacro = () => {
  const [data, setData] = useState();

  useEffect(() => {
    const loadData = async () => {
      const result = await fetchData();
      setData(result);
      // Perform any other operations your macro requires
      await view.emitReadyEvent(); // Notify that the macro is ready
    };

    loadData();
  }, []);

  return <div>{data ? "Macro content loaded" : "Loading..."}</div>;
};

export default MyMacro;

createAdfRendererIframeProps (EAP)

Use createAdfRendererIframeProps when building a Custom UI bodied macro that needs to display its rich-text body content, including embedded Forge apps. This function generates the properties needed for an iframe element to render the ADF document type content of a Custom UI bodied macro.

Prerequisites

• This method is for Custom UI apps only. For UI Kit, use the AdfRenderer component instead.

• Your app must be a Confluence bodied macro with layout:bodied enabled in the macro module properties of the manifest file.

Function signature

1
2
interface FullContext {
  accountId?: string;
  cloudId?: string;
  workspaceId?: string;
  extension: ExtensionData;
  environmentId: string;
  environmentType: EnvironmentType;
  license?: LicenseDetails;
  localId: string;
}

function createAdfRendererIframeProps(
  context: FullContext,
  iframeId?: string
): Promise<{
  id: string;
  src: string;
  onLoad: () => void;
}>;

Arguments

• context: Contextual information for your Custom UI app taken from the getContext method or the useProductContext hook. The ADF document is extracted from context.extension.macro.body.
• iframeId: You can optionally pass an iframe id. Otherwise, an iframe id will be created by default.

Returns

Returns an object with the following properties:

• id: id of the adf renderer wrapper iframe. The value of id will be the same as iframeId if iframeId was provided as an argument.
• src: src of the adf renderer wrapper iframe.
• onLoad: the onLoad function of the adf renderer wrapper iframe which will send the ADF document contents to the iframe once the iframe has initialised.

Example

1
2
import { view } from "@forge/bridge";

function App() {
  // Get the contents of the bodied macro
  const [context, setContext] = useState(null);
  const [iframe, setIframe] = useState(null);

  useEffect(() => {
    view.getContext().then(setContext);
  }, []);

  useEffect(() => {
    if (!context) return;
    // Generate properties for embedded content wrapper
    // Pass in the embedded contents to the function
    // macroBody - any Valid ADF document can be passed in.
    view.createAdfRendererIframeProps(context).then(({ id, src, onLoad }) =>
      // Required iframe props
      // id - id of the iframe so the wrapper knows where to send the embedded macro contents
      // src - src of the embedded content renderer
      // onLoad - sends embedded macro contents once iframe has initialised
      // You can apply any styling you like to the iframe
      setIframe(<iframe id={id} src={src} onLoad={onLoad} />)
    );
  }, [context]);
  return (
    <div>
      <h1>Embedded content</h1>
      {/* Render the embedded content where you want in your app */}
      {iframe || "Loading embedded content..."}
    </div>
  );
}
export default App;

Limitations

• Confluence live pages: This method is not supported in Confluence live pages (also known as whiteboards or live docs).

• Connect macros: Macros built with Atlassian Connect cannot be embedded.

• Modals: Modals in Custom UI embedded macros are not supported.

Supported bridge methods