Rate this page:

Modal API

About

API to render and manipulate extensions of type Modal.

Signature

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
type ModalAction = {
    text: string;
    onClick: () => void;
    isDisabled?: boolean;
    isLoading?: boolean;
    testId?: string;
};

type ModalCloseAction = (e: MouseEvent) => boolean;

type ModalRenderCallback = (container: HTMLElement) => void;

type ModalCleanupCallback = (container: HTMLElement) => void;

enum ModalAppearance {
    'danger' = 'danger',
    'warning' = 'warning',
}

enum ModalWidth {
    'small' = 'small',
    'medium' = 'medium',
    'large' = 'large',
    'x-large' = 'x-large',
}

interface ModalAPI {
    setTitle: (title: string) => ModalAPI;

    setWidth: (width: ModalWidth) => ModalAPI;

    setAppearance: (appearance: ModalAppearance) => ModalAPI;

    closeModal: () => ModalAPI;

    onMount: (callback: ModalRenderCallback) => ModalAPI;

    onUnmount: (callback: ModalCleanupCallback) => ModalAPI;

    setActions: (actions: ModalAction[]) => ModalAPI;

    onClose(callback: ModalCloseAction) => ModalAPI
}

setTitle()

Allows setting a title for the modal.

Arguments

NameTypeDescription
title*stringA string to serve as the title of the modal.

* required

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import { ModalExtension } from '@atlassian/clientside-extensions';

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ModalExtension.factory((extensionAPI, context) => {
    return {
        label: 'Open Modal',
        onAction(modalAPI) {
            modalAPI.setTitle('A cool modal with JS');
        },
    };
});

setWidth()

Allows specifying a width for the modal.

Arguments

NameValues
width*"small" | "medium" | "large" | "x-large"

setAppearance()

Allows specifying an appearance for the modal.

Arguments

NameValues
appearance*"danger" | "warning"

closeModal()

When executed, it will close the modal.

onMount()

Provides a container to render custom content as the body of the modal, and provides an API to interact with the modal once opened.

Callback parameters

NameTypeDescription
containerHTMLElementHTML element to be used as a container to render custom content in the body of the modal.

setActions()

Allows to specify the actions as buttons in the footer of the modal.

Arguments

NameTypeDescription
actions*ModalAction[]

Actions for the modal. It supports the following properties:

text: text content for the button.

onClick: callback to execute when the button is clicked.

isDisabled: if true, the button will be rendered in a disabled state.

isLoading: if true, the button will be rendered in a loading state.

testId: a unique string that appears as a data attribute data-testid on the rendered action element

* required

onClose()

Allows to be notified when the modal is about to be closed from an external action, like the user clicking away from the modal.

Arguments

NameTypeDescription
callbackModalCloseActionCallback that will get called before the modal is closed. If returning false, it will prevent the modal from close; otherwise, the modal will close.

onUnmount()

Allows to set a cleanup callback to be called when the modal container is about to be deleted.

Callback Parameters

NameTypeDescription
containerHTMLElementHTML element that was provided to render custom content in it. It's important to unmount any React component you've mounted in there to avoid keeping the component alive when the container is destroyed.

Usage

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
import { ModalExtension } from '@atlassian/clientside-extensions';

import { getModalContent, confirm, primaryAction, secondaryAction } from './modal';

/**
 * @clientside-extension
 * @extension-point reff.plugins-example-location
 */
export default ModalExtension.factory((extensionAPI, context) => {
    return {
        label: 'Open Modal',
        onAction(modalAPI) {
            modalAPI.setTitle('A cool modal with JS');
            modalAPI.setWidth('small');
            modalAPI.setAppearance('warning');

            modalAPI.onMount(container => {
                // append your content for the modal
                container.innerHTML = getModalContent();

                // set actions for the modal
                modalAPI.setActions([
                    {
                        text: 'Primary',
                        onClick: () => {
                            primaryAction().then(() => {
                                modalAPI.closeModal();
                            });
                        },
                    },
                    {
                        text: 'Secondary',
                        onClick: () => {
                            container.innerHTML = getModalContent({ secondaryClicked: true });
                        },
                    },
                ]);

                // listen when the modal is about to be closed by the user
                modalAPI.onClose(() => {
                    return confirm('Are you sure you want to close this modal?');
                });
            });
        },
    };
});

Rate this page: