Dialog2

Ask a question Design guidelines

Summary

Modal dialogs are used to get a response from a user or reveal critical information that cannot be ignored.

Status

API status: general
Included in AUI core? Not in core You must explicitly require the web resource key.
Web resource key: com.atlassian.auiplugin:dialog2
AMD Module key: require('aui/dialog2')
Experimental API: 5.3
General API: 5.8

Examples

Anatomy of a dialog

In this example, you can see all the various pieces of the dialog's HTML pattern.

Example
AخA
 
<!--
    Renders a static dialog.
    To ensure the dialog is not rendered inline in the page, add:
     * class="aui-layer"
     * aria-hidden="true"
    to this element.
-->
<section id="static-dialog" class="aui-dialog2 aui-dialog2-medium" role="dialog">
    <!-- Dialog header -->
    <header class="aui-dialog2-header">
        <!-- The dialog's title -->
        <h2 class="aui-dialog2-header-main">The modal dialog title</h2>
        <!-- Actions to render on the right of the header -->
        <div class="aui-dialog2-header-secondary">
            <form class="aui" action="#">
                <input id="demo-search" class="text" type="search" name="search">
            </form>
        </div>
        <!-- Close icon -->
        <a class="aui-dialog2-header-close">
            <span class="aui-icon aui-icon-small aui-iconfont-close-dialog">Close</span>
        </a>
    </header>
    <!-- Main dialog content -->
    <div class="aui-dialog2-content">
        <p>Content for the modal dialog.</p>
    </div>
    <!-- Dialog footer -->
    <footer class="aui-dialog2-footer">
        <!-- Actions to render on the right of the footer -->
        <div class="aui-dialog2-footer-actions">
            <button class="aui-button aui-button-primary">Okay</button>
            <button class="aui-button">Next</button>
            <button class="aui-button aui-button-link">Close</button>
        </div>
        <!-- Hint text is rendered on the left of the footer -->
        <div class="aui-dialog2-footer-hint">This is a hint.</div>
    </footer>
</section>

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 class="aui-layer" and aria-hidden="true" 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.

Opening and closing a dialog

You can use JavaScript to make the dialog open and close.

Example
​x
 
<!-- Create a trigger which will be used by the JavaScript -->
<button id="dialog-show-button" class="aui-button">Show dialog</button>
​
<section id="demo-dialog" class="aui-dialog2 aui-dialog2-small aui-layer" role="dialog" aria-hidden="true">
    <header class="aui-dialog2-header">
        <h2 class="aui-dialog2-header-main">Captain...</h2>
        <a class="aui-dialog2-header-close">
            <span class="aui-icon aui-icon-small aui-iconfont-close-dialog">Close</span>
        </a>
    </header>
    <div class="aui-dialog2-content">
        <p>We've detected debris of some sort in a loose orbit.</p>
        <p>I suggest we beam a section aboard for analysis...</p>
    </div>
    <footer class="aui-dialog2-footer">
        <div class="aui-dialog2-footer-actions">
            <button id="dialog-submit-button" class="aui-button aui-button-primary">Make it so</button>
        </div>
    </footer>
</section>
 
// Shows the dialog when the "Show dialog" button is clicked
AJS.$("#dialog-show-button").click(function(e) {
    e.preventDefault();
    AJS.dialog2("#demo-dialog").show();
});
​
// Hides the dialog
AJS.$("#dialog-submit-button").click(function (e) {
    e.preventDefault();
    AJS.dialog2("#demo-dialog").hide();
});

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.

Example
 
<button id="warning-dialog-show-button" class="aui-button">Show warning dialog</button>
​
<section id="demo-warning-dialog" class="aui-dialog2 aui-dialog2-medium aui-dialog2-warning aui-layer" role="dialog" aria-hidden="true">
    <header class="aui-dialog2-header">
        <h2 class="aui-dialog2-header-main">Confirm you want to delete this thing</h2>
        <a class="aui-dialog2-header-close">
            <span class="aui-icon aui-icon-small aui-iconfont-close-dialog">Close</span>
        </a>
    </header>
    <div class="aui-dialog2-content">
        <p>If you do this, there's no going back. Are you certain that you want this thing to be gone forever?</p>
    </div>
    <footer class="aui-dialog2-footer">
        <div class="aui-dialog2-footer-actions">
            <button id="warning-dialog-confirm" class="aui-button aui-button-primary">Delete the thing</button>
            <button id="warning-dialog-cancel" class="aui-button aui-button-link">Cancel</button>
        </div>
    </footer>
</section>
 
// Shows the warning dialog when the "Show warning dialog" button is clicked
AJS.$("#warning-dialog-show-button").click(function (e) {
    e.preventDefault();
    AJS.dialog2("#demo-warning-dialog").show();
});
​
AJS.$(document).on("click", "#demo-warning-dialog button", function (e) {
    e.preventDefault();
    AJS.dialog2("#demo-warning-dialog").hide();
});

Options

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.
 
<section class="aui-dialog2 aui-dialog2-small"
         role="dialog"
         aria-hidden="true">
    <!-- inner content -->
</section>
.aui-dialog2-warning Gives the dialog's header a red background color.
 
<section class="aui-dialog2 aui-dialog2-warning"
         role="dialog"
         aria-hidden="true">
    <!-- inner content -->
</section>
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.
 
<section class="aui-dialog2"
         data-aui-modal="true"
         role="dialog"
         aria-hidden="true">
    <!-- inner content -->
</section>
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.
 
<section class="aui-dialog2"
         data-aui-remove-on-hide="true"
         role="dialog"
         aria-hidden="true">
    <!-- inner content -->
</section>
data-aui-focus-selector selector Controls the element that is focussed when the dialog is opened.
 
<section class="aui-dialog2"
         data-aui-focus-selector=".aui-dialog2-content :input:visible:enabled"
         role="dialog"
         aria-hidden="true">
    <!-- inner content -->
</section>

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.

 
var demoDialog = AJS.dialog2("#demo-dialog");

Methods

Method Description Example Usage
show Shows a dialog.
 
AJS.dialog2("#demo-dialog").show();
hide Hides a dialog.
 
AJS.dialog2("#demo-dialog").hide();
remove Removes the dialog from the DOM.
 
AJS.dialog2("#demo-dialog").remove();

Events

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.
 
AJS.dialog2("#demo-dialog").on("show", function() {
    console.log("demo-dialog was shown");
});
hide Triggered when a dialog instance is hidden.
 
AJS.dialog2("#demo-dialog").on("hide", function() {
    console.log("demo-dialog was hidden");
});
global show Triggered when any dialog is shown.
 
AJS.dialog2.on("show", function() {
    console.log("a dialog was shown");
});
global hide Triggered when any dialog is hidden.
 
AJS.dialog2.on("hide", function() {
    console.log("a dialog was hidden");
});