Modal dialogs are used to get a response from a user or reveal extra information related to a given scenario.


For the best practices on usage please refer to Atlas Kit Dialog usage documentation.

For the best practices on accessibility please refer to WAI Guidelines on Dialog.

There are also Dialog A11y specifications for AUI available inside of Atlassian.


API status: general
Web resource key: com.atlassian.auiplugin:aui-dialog2
AMD Module key: require('aui/dialog2')
Experimental API: 5.3
General API: 5.8


Anatomy of a dialog

Below you can see an overview of the dialog HTML pattern.

On its own, the dialog HTML pattern itself is static — the contents are added to the page inline. To ensure the dialog does not get rendered to the page, you should add aui-layer class and hidden attribute to the dialog element.

Note that in the footer, the hint text (class="aui-dialog2-footer-hint") should be placed in the DOM below the footer actions (class="aui-dialog2-footer-actions") even though the hint text appears to the left of the footer actions.

Initial focus management

When working with Dialogs initial focus is one of the most important things impacting user experience.

This is how Dialog2 handles the focus:

  1. find autofocus attributes in Dialog and focus the first one if found
  2. if there are no autofocus attributes, find all focusable controls and focus the first one
  3. if still nothing was focused, focus Dialog container element

When adding Dialog to the page, you need to think about what would be the best initial focus element in this specific Dialog. If it's not focused by default, you should consider adding autofocus attribute to it, or restructuring Dialog contents.

If you are not sure what is the best approach in your case, please refer to guides from Usage section of the page.

Opening and closing a dialog

By default the dialog closes after the close button or the blanket is clicked.

To make the dialog open and close in other cases you can use .show and .hide methods.

Focus management after dialog is closed

By default after the dialog is closed the focus returns to the element that was focused before it was opened.

However there are cases in which you have to explicitly set the focus after the dialog is closed, e.g. the element focused before dialog opening no longer exists in the document. While deciding which element should be focused keep in mind the natural flow of operation and user journey. Subscribe to hide event to achieve the required behaviour.

A warning dialog

Use this dialog type when you're representing a destructive action, and want the end-user to think more carefully about how they proceed.


HTML attributes

Dialog2 configuration options are expressed through markup.

Class Description Example Usage
aui-dialog2-small | aui-dialog2-medium | aui-dialog2-large | aui-dialog2-xlarge Controls the size of the dialog according to ADG size specifications.
.aui-dialog2-warning Gives the dialog's header a red background color.
Attribute Values Description Example Usage
data-aui-modal true Specifies that the dialog is modal. Modal dialogs have no close icon in the top right corner, and cannot be closed by clicking on the blanket behind it.
data-aui-remove-on-hide true Specifies that the dialog element should be removed from the DOM when it is hidden, either by clicking on the close icon, clicking on the blanket behind the dialog, or calling the hide() method.
data-aui-focus-selectorDeprecated selector

Controls the element that is focussed when the dialog is opened. By default the focus goes to the dialog element itself to meet the accessibility expectations in most common cases.

JavaScript API

To get a reference to the API for a dialog2 instance, call AJS.dialog2(selector), where selector can be a selector string, DOM node, or jQuery element.


Method Description Example Usage
show Shows a dialog.
hide Hides a dialog.
remove Removes the dialog from the DOM.


Events are triggered when dialogs are shown or closed. These can be listened to for a single dialog instance, or for all dialogs.

Event Description Example Usage
show Triggered when a dialog instance is shown.
hide Triggered when a dialog instance is hidden.
global show Triggered when any dialog is shown.
global hide Triggered when any dialog is hidden.