Modal

The Modal class enables your custom UI app to open a modal dialog with a specified resource.

Class signature

1
2
interface ModalOptions {
  resource?: string | null;
  onClose?: (payload?: any) => any;
  size?: 'small' | 'medium' | 'large' | 'xlarge' | 'max';
  context?: any;
  closeOnEscape?: boolean;
  closeOnOverlayClick?: boolean;
}

class Modal {
  constructor(opts?: ModalOptions);
  open(): Promise<void>;
}

Arguments

• resource: The key of the static resource to open in the modal dialog. If not provided, resource defaults current resource.

• onClose: A callback function to run when the modal dialog is closed. The function accepts an optional payload that is passed when calling view.close(payload) from inside the modal resource.

• size: The size of the modal dialog.

  • small - w: 400px h: 20vh minHeight: 320px

  • medium - w: 600px h: 40vh minHeight: 520px

  • large - w: 800px h: 70vh minHeight: 720px

  • xlarge - w: 968px h: 90vh

  • max - w: 100% h: 100%

    Currently in Jira, the xlarge size has a 100% width and will be changed to 968px on the 27/02/2023.

    Please use the max modal size to retain the same behavior of a 100% width modal that xlarge uses.

• context: Custom context that can be added to the context in the modal resource. It will appear under the modal key in the context object returned from view.getContext().

• closeOnEscape: If set to false, the modal will not close when pressing escape.

• closeOnOverlayClick: If set to false, the modal will not close when clicking the overlay.

Example

Implementing a custom UI modal requires two files:

1. the index.js file in your app logic
2. the resource file you defined in the manifest file, which is the my-modal-resource.js file in the example below

index.js

1
2
import { Modal } from '@forge/bridge';

const modal = new Modal({
  resource: 'my-modal-resource',
  onClose: (payload) => {
    console.log('onClose called with', payload);
  },
  size: 'medium',
  context: {
    customKey: 'custom-value',
  },
});

modal.open();

my-modal-resource.js

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

const context = await view.getContext();
const customValue = context.extension.modal.customKey;

view.close({
  formValues: [],
});