UI.displayDialogAsync method

Displays a dialog box in an Office host.

Requirements

Host	Introduced in	Last changed in
Word, Excel, PowerPoint	1.1	1.1
Outlook	Mailbox 1.4	Mailbox 1.4

This method is available in the DialogApi requirement set for Word, Excel, or PowerPoint add-ins, and in the Mailbox requirement set 1.4 for Outlook. To specify the DialogAPI requirement set, use the following in your manifest.

<Requirements> 
  <Sets DefaultMinVersion="1.1"> 
    <Set Name="DialogApi"/> 
  </Sets> 
</Requirements>

To specify the Mailbox 1.4 requirement set, use the following in your manifest.

<Requirements> 
  <Sets DefaultMinVersion="1.4"> 
    <Set Name="Mailbox"/> 
  </Sets> 
</Requirements>

To detect this API at runtime in a Word, Excel, or PowerPoint add-in, use the following code.

if (Office.context.requirements.isSetSupported('DialogApi', 1.1)) {  
  // Use Office UI methods; 
} else { 
  // Alternate path 
}

To detect this API at runtime in an Outlook add-in, use the following code.

if (Office.context.requirements.isSetSupported('Mailbox', 1.4)) {  
  // Use Office UI methods; 
} else { 
  // Alternate path 
}

Alternatively, you can check if the displayDialogAsync method is undefined before using it.

if (Office.context.ui.displayDialogAsync !== undefined) {
  // Use Office UI methods
}

Supported platforms

For information about supported platforms, see Dialog API requirement sets.

Syntax

Office.context.ui.displayDialogAsync(startAddress, options, callback);

Examples

For a simple example that uses the displayDialogAsync method, see Office Add-in Dialog API example on GitHub.

For an examples that show authentication scenarios, see:

Parameters

Parameter	Type	Description
startAddress	string	Accepts the initial HTTPS(TLS) URL that opens in the dialog box. The initial page must be on the same domain as the parent page. 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.
options	object	Optional. Accepts an options object to define dialog behaviors.
callback	object	Accepts a callback method to handle the dialog creation attempt.

Configuration options

The following configuration options are available for a dialog box.

Property	Type	Description
width	int	Optional. Defines the width of the dialog box as a percentage of the current display. The default value is 80%. The minimum resolution is 250 pixels.
height	int	Optional. Defines the height of the dialog box as a percentage of the current display. The default value is 80%. The minimum resolution is 150 pixels.
displayInIframe	bool	Optional. Determines whether the dialog box should be displayed within an IFrame. This setting is only applicable in Office Online clients, and is ignored by other platforms. The following are the possible values: false (default) - The dialog will be displayed as a new browser window (pop-up). Recommended for authentication pages that cannot be displayed in an IFrame. true - The dialog will be displayed as a floating overlay with an IFrame. This is best for user experience and performance.

Callback value

When the function you passed to the callback parameter executes, it receives an AsyncResult object that you can access from the callback function's only parameter.

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 to
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.

Errors from displayDialogAsync

In addition to general platform and system errors, the following errors are specific to calling displayDialogAsync.

Code number	Meaning
12004	The domain of the URL passed to `displayDialogAsync` is not 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.

Design considerations

The following design considerations apply to dialog boxes:

An Office Add-in can have only one dialog box open at any time.
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 host 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 ShowTaspane 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.

For a design pattern that you can use to create a dialog box, see Client Dialog in the Office Add-in UX Design Patterns repository on GitHub.

Docs