Office.UI interface

Adds an event handler to the object using the specified event type.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement set: DialogAPI 1.2

You can add multiple event handlers for the specified event type as long as the name of each event handler function is unique.

Adds an event handler to the object using the specified event type.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Parameters

Returns

Remarks

Requirement set: DialogAPI 1.2

You can add multiple event handlers for the specified event type as long as the name of each event handler function is unique.

Examples

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

Closes the UI container where the JavaScript is executing.

closeContainer(): void;

Returns

Remarks

Applications: Excel, Outlook (Minimum requirement set: Mailbox 1.5), PowerPoint, Word

Requirement sets:

• DialogAPI

• Mailbox 1.5

The behavior of this method is specified by the following:

• Called from a UI-less command button: No effect. Any dialog opened by displayDialogAsync will remain open.

• Called from a task pane: The task pane will close. Any dialog opened by displayDialogAsync will also close. If the task pane supports pinning and was pinned by the user, it will be un-pinned.

• Called from a module extension: No effect.

Examples

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

Displays a dialog to show or collect information from the user or to facilitate Web navigation.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

Parameters

Returns

Remarks

Applications: Excel, Outlook, PowerPoint, Word

Requirement sets:

• DialogAPI

• Mailbox 1.4

This method is available in the DialogApi requirement set for Excel, PowerPoint, or Word add-ins, and in the Mailbox requirement set 1.4 for Outlook. For more on how to specify a requirement set in your manifest, see Specify Office applications and API requirements, if you're using the add-in only manifest. If you're using the unified manifest for Microsoft 365, see Office Add-ins with the unified app manifest for Microsoft 365.

The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial page loads, you can go to other domains.

Any page calling Office.context.ui.messageParent must also be on the same domain as the parent page.

Design considerations:

The following design considerations apply to dialog boxes.

• An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the same time from Add-in Commands (custom ribbon buttons or menu items).

• Every dialog box can be moved and resized by the user.

• Every dialog box is centered on the screen when opened.

• Dialog boxes appear on top of the application and in the order in which they were created.

Use a dialog box to:

• Display authentication pages to collect user credentials.

• Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.

• Temporarily increase the surface area that a user has available to complete a task.

Do not use a dialog box to interact with a document. Use a task pane instead.

displayDialogAsync Errors

In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the following information.

Examples

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

Displays a dialog to show or collect information from the user or to facilitate Web navigation.

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

Parameters

Returns

Remarks

Applications: Excel, Outlook, PowerPoint, Word

Requirement sets:

• DialogAPI

• Mailbox 1.4

This method is available in the DialogApi requirement set for Excel, PowerPoint, or Word add-ins, and in the Mailbox requirement set 1.4 for Outlook. For more on how to specify a requirement set in your manifest, see Specify Office applications and API requirements, if you're using the add-in only manifest. If you're using the unified manifest for Microsoft 365, see Office Add-ins with the unified app manifest for Microsoft 365.

The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial page loads, you can go to other domains.

Any page calling Office.context.ui.messageParent must also be on the same domain as the parent page.

Design considerations:

The following design considerations apply to dialog boxes.

• An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the same time from Add-in Commands (custom ribbon buttons or menu items).

• Every dialog box can be moved and resized by the user.

• Every dialog box is centered on the screen when opened.

• Dialog boxes appear on top of the application and in the order in which they were created.

Use a dialog box to:

• Display authentication pages to collect user credentials.

• Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.

• Temporarily increase the surface area that a user has available to complete a task.

Do not use a dialog box to interact with a document. Use a task pane instead.

displayDialogAsync Errors

In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the following information.

Delivers a message from the dialog box to its parent/opener page.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Parameters

Returns

Remarks

Applications: Excel, Outlook, PowerPoint, Word

Requirement sets:

• DialogAPI

• Mailbox 1.4

• If the messageOptions parameter is used, DialogOrigin 1.1 is also required.

Examples

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

Opens a browser window and loads the specified URL.

openBrowserWindow(url: string): void;

Parameters

Returns

Remarks

Requirement set: OpenBrowserWindowAPI 1.1

Examples

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();