Office.UI interface

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.

Visit "Use the Dialog API in your Office Add-ins" for more information.

Remarks

Examples

// Get an Office.UI object and use it to open a dialog with a specified size. 
const uiContext = Office.context.ui;
uiContext.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Methods

addHandlerAsync(eventType, handler, options, callback)

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

addHandlerAsync(eventType, handler, callback)

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

closeContainer()

Closes the UI container where the JavaScript is executing.

displayDialogAsync(startAddress, options, callback)

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

displayDialogAsync(startAddress, callback)

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

messageParent(message, messageOptions)

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

openBrowserWindow(url)

Opens a browser window and loads the specified URL.

Method Details

addHandlerAsync(eventType, handler, options, callback)

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

eventType
Office.EventType

Specifies the type of event to add. This must be Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

The event handler function to add, whose only parameter is of type Office.DialogParentMessageReceivedEventArgs.

options
Office.AsyncContextOptions

Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback

(result: Office.AsyncResult<void>) => void

Optional. A function that is invoked when the handler registration returns, whose only parameter is of type Office.AsyncResult.

Returns

void

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.

addHandlerAsync(eventType, handler, callback)

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

eventType
Office.EventType

Specifies the type of event to add. This must be Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

The event handler function to add, whose only parameter is of type Office.DialogParentMessageReceivedEventArgs.

callback

(result: Office.AsyncResult<void>) => void

Optional. A function that is invoked when the handler registration returns, whose only parameter is of type Office.AsyncResult.

Returns

void

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;
    }
}

closeContainer()

Closes the UI container where the JavaScript is executing.

closeContainer(): void;

Returns

void

Remarks

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

Requirement sets:

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();

displayDialogAsync(startAddress, options, callback)

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

startAddress

string

Accepts the initial full HTTPS URL that opens in the dialog. Relative URLs mustn't be used.

options
Office.DialogOptions

Optional. Accepts an Office.DialogOptions object to define dialog display.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Optional. Accepts a callback function to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object.

Returns

void

Remarks

Applications: Excel, Outlook, PowerPoint, Word

Requirement sets:

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

Code number Meaning
12004 The domain of the URL passed to displayDialogAsync isn't trusted. The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the AppDomains section of the add-in manifest.
12005 The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In some versions of Office, the error message returned with 12005 is the same one returned for 12004.)
12007 A dialog box is already opened from the task pane. A task pane add-in can only have one dialog box open at a time.
12009 The user chose to ignore the dialog box. This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.

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

Property Use
AsyncResult.value Access the Dialog object.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext Access your user-defined object or value, if you passed one as the asyncContext parameter.

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);
        });
    }
);

displayDialogAsync(startAddress, callback)

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

startAddress

string

Accepts the initial full HTTPS URL that opens in the dialog. Relative URLs mustn't be used.

callback

(result: Office.AsyncResult<Office.Dialog>) => void

Optional. Accepts a callback function to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object.

Returns

void

Remarks

Applications: Excel, Outlook, PowerPoint, Word

Requirement sets:

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

Code number Meaning
12004 The domain of the URL passed to displayDialogAsync isn't trusted. The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the AppDomains section of the add-in manifest.
12005 The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In some versions of Office, the error message returned with 12005 is the same one returned for 12004.)
12007 A dialog box is already opened from the task pane. A task pane add-in can only have one dialog box open at a time.
12009 The user chose to ignore the dialog box. This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.

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

Property Use
AsyncResult.value Access the Dialog object.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext Access your user-defined object or value, if you passed one as the asyncContext parameter.

messageParent(message, messageOptions)

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

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

Parameters

message

string

Accepts a message from the dialog to deliver to the add-in. Anything that can serialized to a string including JSON and XML can be sent.

messageOptions
Office.DialogMessageOptions

Optional. Provides options for how to send the message.

Returns

void

Remarks

Applications: Excel, Outlook, PowerPoint, Word

Requirement sets:

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));
}

openBrowserWindow(url)

Opens a browser window and loads the specified URL.

openBrowserWindow(url: string): void;

Parameters

url

string

The full URL to be opened including protocol (e.g., https), and port number, if any.

Returns

void

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();