Inline Dialog

Ask a question Design guidelines
This documentation is for the web component Inline Dialog API.

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

API status: general
Included in AUI core? Not in core You must explicitly require the web resource key.
Web resource key: com.atlassian.auiplugin:aui-inline-dialog2
AMD Module key: N/A
Experimental since: 5.7
General API status: 5.9

Example

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

Buttons as triggers

Buttons can serve as triggers as long as they have the data-aui-trigger boolean attribute.

Behaviour

Opening

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

Programmatically opening

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

Opening at page load

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

Boolean attributes

As per the boolean attribute spec, a boolean attribute such as open="false" is interpreted as true.

Opening by hovering over the trigger

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

Or by setting the respondsTo JavaScript property:

Hovering includes having keyboard focus

As an accessibility enhancement, giving an inline dialog's trigger focus will also enable hovering behaviour.

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:

Prevent automatic closing

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

Or by setting the persistent JavaScript property:

Appearance

Alignment

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

The alignment attribute takes two positional arguments 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:

Alignment is rendered once

An inline dialog's alignment cannot be changed once the inline dialog has been opened. However, it will continue to be responsive to space constraints.

Space-constrained alignment

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

API Reference

Attributes and properties

Name Attribute Property Type Description
id is an attribute is a property String

Required when using a trigger to interact with an inline dialog but not required for the inline dialog to function.

Defaults to null.
alignment is an attribute is not a property String

Specifies an inline dialog's alignment with respect to its trigger. The inline dialog is not positioned if this is not specified.

Defaults to "right middle".

Show all values

open is an attribute is a property Boolean

When set it either hides or shows the element based on whether the incoming value is falsy or truthy. When accessed it will return whether or not the inline dialog is open.

Defaults to false.
persistent is an attribute is a property Boolean

Specifies that an inline dialog is persistent. Persistent inline dialogs cannot be closed by outside click or escape.

Defaults to false.
responds-to is an attribute is a property String

Determines the type of interaction a trigger will have with its inline dialog.

Values:

  • toggle default - will respond to click event on the trigger.
  • hover - will respond to mouseover, mouseout, focus, blur events on the trigger.

Methods

There are no methods.

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.

Event Description Preventable Bubbles
aui-show Triggered before an inline dialog instance is shown. Yes. Prevents it from showing. Yes
aui-hide Triggered before an inline dialog instance is hidden. Yes. Prevents it from hiding. Yes