Inline dialogs

Summary

A container for secondary content/controls to be displayed on user request. Consider this component as displayed in context to the triggering control with the dialog overlaying the page content.

An inline dialog should be preferred over a modal dialog when a connection between the action has a clear benefit versus having a lower user focus.

Status

Behaviour

Triggering

An inline dialog can be opened by a Trigger element. Any interactive element can be made in to a trigger — the typical elements to use are either <button> or <a>

Associate a trigger (data-aui-trigger) to an inline dialog by setting the trigger element's aria-controls attribute to the id of the inline dialog:

<a data-aui-trigger aria-controls="more-details" href="#more-details">

    A hyperlink as a trigger

</a>

<button data-aui-trigger aria-controls="more-details">

    A button as a trigger

</button>

<aui-inline-dialog id="more-details" aria-label="Example dialog">

    <p>Lorem ipsum.</p>

</aui-inline-dialog>

Opening

An inline dialog will, by default, open when a user clicks its trigger, but can be made to open:

• programmatically,
• automatically at page load, or
• when hovering over its trigger. deprecated

Programmatically opening

To programmatically open an inline dialog, set its open property or add the open boolean attribute:

var inlineDialog = document.getElementById('my-inline-dialog');

inlineDialog.open = true;

inlineDialog.setAttribute('open', '');  // Equivalent to line above.

Opening at page load

To make an inline dialog open at page load, simply specify the open boolean attribute:

<a data-aui-trigger aria-controls="start-open" href="#start-open">

    This inline dialog starts open

</a>

<aui-inline-dialog id="start-open" open aria-label="Open from the start">

    <p>Lorem ipsum.</p>

    <a role="button" tabindex="0" class="aui-button aui-button-link">Close</a>

</aui-inline-dialog>

Opening by hovering over the trigger deprecated

Make an inline dialog show when hovering over the trigger by setting the inline dialog's responds-to attribute:

<a data-aui-trigger aria-controls="show-on-hover" href="#show-on-hover">

    Hover to show contents

</a>

<aui-inline-dialog id="show-on-hover" responds-to="hover">

    <p>Lorem ipsum.</p>

</aui-inline-dialog>

Or by setting the respondsTo JavaScript property:

var inlineDialog = document.getElementById('show-on-hover')

inlineDialog.respondsTo = 'hover';

Closing

Inline dialogs will automatically close when the user clicks outside the inline dialog or presses ESC. Inline dialogs that open on hover close when the user stops hovering over either the trigger or the inline dialog itself.

An inline dialog that is set to not automatically close can only be closed programmatically, e.g., via an event handler bound to a close button.

Programmatically closing

To programmatically close an inline dialog, set its open property or remove its open attribute:

var inlineDialog = document.getElementById('my-inline-dialog');

inlineDialog.open = false;

inlineDialog.removeAttribute('open');  // Equivalent to line above.

Prevent automatic closing

Inline dialogs can be forced to remain open via the persistent boolean attribute:

<a data-aui-trigger aria-controls="stays-open" href="#stays-open">

    This inline dialog stays open

</a>

<aui-inline-dialog id="stays-open" persistent aria-label="Persistent dialog">

    <p>Lorem ipsum.</p>

    <a role="button" tabindex="0" class="aui-button aui-button-link">Close</a>

</aui-inline-dialog>

Or by setting the persistent JavaScript property:

var inlineDialog = document.getElementById('stays-open')

inlineDialog.persistent = true;

Accessibility

Label

Make sure you set aria-label on aui-inline-dialog element to give screen reader friendly description of the the dialog's content. When aria-label is missing the AT will read whole content of the dialog.

Appearance

Alignment

An inline dialog can be aligned, relative to its trigger, along twelve different points, via the alignment attribute:

<a data-aui-trigger aria-controls="align-bottom-right" href="#align-bottom-right">

    Bottom right alignment

</a>

<aui-inline-dialog id="align-bottom-right" alignment="bottom right" aria-label="Alignment example">

    <p>Lorem ipsum.</p>

</aui-inline-dialog>

The alignment attribute takes two positional arguments (deprecated - arrows will be removed in AUI 10) in the format alignment="edge edge-position", where

• edge specifies what edge to align the inline dialog's arrow to, and
• edge-position specifies where on that edge the arrow should appear.

See the alignment API reference for all valid combinations, or test the combinations below:

Space-constrained alignment

If there is not enough room to display an inline dialog with the desired alignment the inline dialog will flip alignment.

<a data-aui-trigger aria-controls="try-right-middle" href="#try-right-middle">

    Right middle alignment, but flips left

</a>

<aui-inline-dialog id="try-right-middle" alignment="right middle" aria-label="Flipping dialog">

    <p>Lorem ipsum.</p>

</aui-inline-dialog>

API Reference

Attributes and properties

Events

Events are triggered when inline dialogs are shown and hidden. These events are triggered natively on the component. You can bind to the the inline dialog element for instance specific events, or rely on event bubbling and bind to the document to receive events for every show and hide.

A11Y guidelines

Side note: whether you'd follow these guidelines or not, it's always advised to at least test your markup with a screen reader software.

Default a11y attributes

The next two attributes aria-expanded="false" and aria-haspopup="true" will be added to the trigger element by default along with role="group" which will be added to the aui-inline-dialog element.

• aria-haspopup="true" indicates that the trigger is an interactive element which opens popup element.
• aria-expanded="false" indicates the current state of the trigger. By default, the popup is collapsed.
• role="group" indicates the element contains the list of the elements that are related to certain functionality/collection.

Change role of the popup element

In case there is a need to change role/type of the popup element it is possible by adding the role="..." attribute manually to the aui-inline-dialog element. It will not change the functionality of the Inline Dialog and the trigger, the only role="dialog" disables/removes the next attribute from the trigger aria-haspopup and aria-expanded

<a data-aui-trigger aria-controls="dialog-with-role-dialog" href="#dialog-with-role-dialog">

    Open dialog

</a>

<aui-inline-dialog id="dialog-with-role-dialog" role="dialog" aria-labelledby="dialog-with-role-dialog-header" aria-describedby="dialog-with-role-dialog-content">

    <h3 id="dialog-with-role-dialog-header">Dialog name</h3>

    <p id="dialog-with-role-dialog-content">

        Dialog with <code>role="dialog"</code> attribute.

    </p>

</aui-inline-dialog>

aria-labelledby & aria-describedby attributes

It is recommended to use aria-labelledby and aria-describedby attributes to reference other elements to provide accessible name and description for the inline dialog.

<a data-aui-trigger aria-controls="dialog-with-aria-attr" href="#dialog-with-aria-attr">

    Open dialog

</a>

<aui-inline-dialog id="dialog-with-aria-attr" aria-labelledby="dialog-with-aria-attr-header" aria-describedby="dialog-with-aria-attr-content">

    <h3 id="dialog-with-aria-attr-header">Dialog name</h3>

    <p id="dialog-with-aria-attr-content">

        Dialog with <code>aria-labelledby</code> and <code>aria-describedby</code> attributes

    </p>

</aui-inline-dialog>

aria-label attribute

As an alternative of aria-labelledby you can use aria-label attribute to provide accessible name for the inline dialog. Especially it is useful when:

• you are implementing a custom control component;
• there is no a header element inside;
• the name of the inline dialog does not match with an inner header;
• there are nested controls.

<a data-aui-trigger aria-controls="dialog-with-aria-label" href="#dialog-with-aria-label">

    Open dialog

</a>

<aui-inline-dialog id="dialog-with-aria-label" aria-label="Dialog name">

    <p>Lorem ipsum.</p>

</aui-inline-dialog>

aui-focus-trap attribute

In case you need to create a custom component based on the Inline Dialog that should trap the focus inside you can use aui-focus-trap="true" attribute.

<a data-aui-trigger aria-controls="dialog-with-focus-trap" href="#dialog-with-focus-trap">

    Open me using keyboard

</a>

<aui-inline-dialog id="dialog-with-focus-trap" aria-label="Dialog name" aui-focus-trap="true">

    <p>The focus trap on the popup element.</p>

</aui-inline-dialog>

<a data-aui-trigger aria-controls="dialog-with-focus-trap2" href="#dialog-with-focus-trap2">

    Open me using keyboard

</a>

<aui-inline-dialog id="dialog-with-focus-trap2" aria-label="Dialog task" aui-focus-trap="true">

    <form class="aui">

        <div class="field-group">

            <label for="description-input">Description</label>

            <textarea class="textarea" name="description-input" id="description-input" placeholder="Description here..."></textarea>

        </div>

        <div class="field-group">

            <label for="comment-input">Comment</label>

            <textarea class="textarea" name="comment-input" id="comment-input" placeholder="Your comment here..."></textarea>

        </div>

    </form>

</aui-inline-dialog>

Recommendation

Please use the Web Accessibility Initiative (WAI) patterns as a reference for implementing accessible components.