Dropdowns

Ask a question

Summary

Dropdown creates a dropdown menu, with optional sections, headings, icons, checkbox items, radio group items and disabled items. Submenus are supported but should be avoided where possible for usability reasons.

Status

API status: general
Web resource key: com.atlassian.auiplugin:aui-dropdown2
AMD Module key: N/A
Experimental API: 5.9
General API: 6
Web Component API: 5.9

Example

Associate a button that acts as the dropdown's trigger (class="aui-dropdown2-trigger") to the dropdown menu (<aui-dropdown-menu>) by setting the trigger's aria-controls attribute to the id of the dropown menu.

Demo code
Result
Atlassian Hacker news Github
Chrome Firefox Safari
Javascript Fortran Rust
​x
 
<button class="aui-button aui-dropdown2-trigger" aria-controls="example-dropdown">
    Dropdown menu
</button>
​
<aui-dropdown-menu id="example-dropdown">
    <aui-section label="Links">
        <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
        <aui-item-link href="http://news.ycombinator.com">Hacker news</aui-item-link>
        <aui-item-link href="http://github.com">Github</aui-item-link>
    </aui-section>
    <aui-section label="Browsers">
        <aui-item-radio interactive checked>Chrome</aui-item-radio>
        <aui-item-radio interactive>Firefox</aui-item-radio>
        <aui-item-radio interactive disabled>Safari</aui-item-radio>
    </aui-section>
    <aui-section label="Languages">
        <aui-item-checkbox interactive checked>Javascript</aui-item-checkbox>
        <aui-item-checkbox interactive>Fortran</aui-item-checkbox>
        <aui-item-checkbox interactive>Rust</aui-item-checkbox>
    </aui-section>
</aui-dropdown-menu>

Code

Sections

An <aui-section> is used to separate groups of related items, and may include a heading. They can contain a group of

To give a section a heading add the label attribute:

Demo code
Result
Amazon Apple Facebook Google
Atlassian
 
<aui-dropdown-menu id="sections-with-headings">
    <aui-section label="Favourites">
        <aui-item-link href="https://amazon.com">Amazon</aui-item-link>
        <aui-item-link href="https://apple.com">Apple</aui-item-link>
        <aui-item-link href="https://facebook.com">Facebook</aui-item-link>
        <aui-item-link href="https://google.com">Google</aui-item-link>
    </aui-section>
    <aui-section label="Recently visited">
        <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
    </aui-section>
</aui-dropdown-menu>

Use <aui-item-link> elements with the href attribute specified to add link items to a dropdown.

Demo code
Result
Profile Account settings Inbox
 
<aui-dropdown-menu id="link-items">
    <aui-section label="Links">
        <aui-item-link href="https://example.com#profile">Profile</aui-item-link>
        <aui-item-link href="https://example.com#account-settings">Account settings</aui-item-link>
        <aui-item-link href="https://example.com#inbox">Inbox</aui-item-link>
    </aui-section>
</aui-dropdown-menu>

To add a submenu to a dropdown, create an <aui-dropdown-menu> containing the submenu content, and set the for attribute of the <aui-item-link> element to the id of the <aui-dropdown-menu> submenu:

Demo code
Result
Amazon Apple Facebook Google
Atlassian
 
<button class="aui-button aui-dropdown2-trigger" aria-controls="has-submenu">
    Dropdown with submenu
</button>
​
<aui-dropdown-menu id="has-submenu">
    <aui-section label="Links">
        <aui-item-link href="https://amazon.com">Amazon</aui-item-link>
        <aui-item-link href="https://apple.com">Apple</aui-item-link>
        <aui-item-link href="https://facebook.com">Facebook</aui-item-link>
        <aui-item-link href="https://google.com">Google</aui-item-link>
        <aui-item-link for="recently-visited">Recently visited</aui-item-link>
    </aui-section>
</aui-dropdown-menu>
​
<aui-dropdown-menu id="recently-visited">
    <aui-section>
        <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
    </aui-section>
</aui-dropdown-menu>

Avoid submenus where possible

For usability reasons, submenus should be avoided where possible.

Checkboxes

Use <aui-item-checkbox> elements when you want to present options the user can select or enable.

Demo code
Result
Javascript Fortran Rust
 
<aui-dropdown-menu id="checkbox-items">
    <aui-section label="Languages">
        <aui-item-checkbox interactive checked>Javascript</aui-item-checkbox>
        <aui-item-checkbox interactive>Fortran</aui-item-checkbox>
        <aui-item-checkbox interactive>Rust</aui-item-checkbox>
    </aui-section>
</aui-dropdown-menu>

Use interactive with checkboxes and radios

It's recommended to use the interactive boolean attribute on checkbox and radio items in dropdown menus to keep the dropdown open when users click those items.

Disabling checkboxes and radios

Add the disabled boolean attribute to checkbox and radio items to disable them.

Responding to events

Listen to change events fired by <aui-item-checkbox> elements to respond to users selecting items, examining the checked attribute to determine whether the item was checked or unchecked:

Demo code
Result
Javascript Fortran Rust
 
var dropdown = document.getElementById('is-checkbox-checked');
dropdown.addEventListener('change', function (e) {
    var isChecked = e.target.hasAttribute('checked');
    if (isChecked) {
        console.log(e.target.textContent, 'was checked.');
    } else {
        console.log(e.target.textContent, 'was unchecked.');
    }
});

Radios

Similar to checkboxes, use <aui-item-radio> elements to present a set of mutually exclusive options to the user:

Demo code
Result
Chrome Firefox Safari
 
<aui-dropdown-menu id="radio-items">
    <aui-section label="Browsers">
        <aui-item-radio interactive checked>Chrome</aui-item-radio>
        <aui-item-radio interactive>Firefox</aui-item-radio>
        <aui-item-radio interactive>Safari</aui-item-radio>
    </aui-section>
</aui-dropdown-menu>

Group radio items with sections

Only one radio item can be selected inside each section, so use an <aui-section> to group a set of <aui-item-radio> elements together.

Responding to events

Listen to change events fired by the <aui-item-radio> elements to be notified when the previous radio item is deselected and the new item is selected, examining the checked attribute to differentiate between the two:

Demo code
Result
Chrome Firefox Safari
 
var section = document.querySelector('aui-section#browsers');
section.addEventListener('change', function (e) {
    var tagName = e.target.tagName.toLowerCase();
    if (tagName === 'aui-item-radio') {
        if (e.target.hasAttribute('checked')) {
            console.log(e.target.textContent, 'was selected.');
        } else {
            console.log(e.target.textContent, 'was deselected.');
        }
    }
});

Order of radio change events is not guaranteed

When a new radio is selected, the change event for the previously selected item being deselected may come before or after the event for the new item being selected, so it's best to examine the checked attribute to differentiate.

Icons

If you require icons in your dropdown menus then unfortunately, at this time the dropdown web component does not support what you want to achieve. Fortunately you can still use the existing dropdown2 HTML component to achieve this. Documentation for the dropdown2 HTML component can be found here: Dropdown2 HTML componentent documentation

Appearance

Alignment

A dropdown will be left-aligned and will extend to the right unless there is no space in its container, in which case it will flip and extend to the left. By default, this container is the viewport.

In order to specify a container for alignment, set the data-aui-alignment-container attribute on the trigger element to a selector matching the container element:

Demo code
Result
Amazon Apple
Facebook Google
 
<div id="alignment-container">
    <button class="aui-button aui-dropdown2-trigger" aria-controls="left-aligned" data-aui-alignment-container="#alignment-container">
        Left-aligned dropdown
    </button>
    <button class="aui-button aui-dropdown2-trigger" aria-controls="right-aligned" data-aui-alignment-container="#alignment-container">
        Right-aligned dropdown
    </button>
</div>
​
<aui-dropdown-menu id="left-aligned">
    <aui-section>
        <aui-item-link href="http://amazon.com">Amazon</aui-item-link>
        <aui-item-link href="http://apple.com">Apple</aui-item-link>
    </aui-section>
</aui-dropdown-menu>
​
<aui-dropdown-menu id="right-aligned">
    <aui-section>
        <aui-item-link href="https://facebook.com">Facebook</aui-item-link>
        <aui-item-link href="https://google.com">Google</aui-item-link>
    </aui-section>
</aui-dropdown-menu>

Sizing

The size of the dropdown can be controlled by adding the aui-list-truncate class to the <aui-section> element and applying the min-width and max-width styles to the <aui-dropdown-menu>.

Options will be truncated to a single line matching the specified width:

Demo code
Result
Short label text
Especially long label text that contains enough text to feed a walrus and also to cause this list item to flow over multiple lines
 
<aui-dropdown-menu id="has-min-width">
    <aui-section class="aui-list-truncate">
        <aui-item-link href="#short">Short label text</aui-item-link>
    </aui-section>
</aui-dropdown-menu>
​
<aui-dropdown-menu id="has-max-width">
    <aui-section class="aui-list-truncate">
        <aui-item-link href="#long">
            Especially long label text that contains enough text to feed a walrus
            and also to cause this list item to flow over multiple lines
        </aui-item-link>
    </aui-section>
</aui-dropdown-menu>
 
#has-min-width {
    min-width: 300px;
}
#has-max-width {
    max-width: 100px;
}

Disabled items

To apply a disabled style to a dropdown item, set the disabled attribute on the item.

Disabling an item will prevent links from being followed, and checkboxes and radio buttons from being checked.

Demo code
Result
Atlassian Google
Chrome Firefox Safari
Javascript Python
 
<aui-dropdown-menu id="disabled-items">
    <aui-section label="Links">
        <aui-item-link href="https://atlassian.com">Atlassian</aui-item-link>
        <aui-item-link disabled href="https://google.com">Google</aui-item-link>
    </aui-section>
    <aui-section label="Browsers">
        <aui-item-radio interactive checked>Chrome</aui-item-radio>
        <aui-item-radio interactive>Firefox</aui-item-radio>
        <aui-item-radio disabled interactive>Safari</aui-item-radio>
    </aui-section>
    <aui-section label="Languages">
        <aui-item-checkbox interactive checked>Javascript</aui-item-checkbox>
        <aui-item-checkbox disabled interactive>Python</aui-item-checkbox>
    </aui-section>
</aui-dropdown-menu>

Disabled items don't prevent event listeners from firing

Interacting with disabled items may still trigger any event listeners attached to the item itself, so ensure that you have also disabled any additional functionality attached to the item.

Hidden items

To hide a section or menu item in a dropdown, set the hidden attribute on the item.

Hidden items will not appear when the dropdown menu is displayed.

Demo code
Result
Profile Inbox
 
<aui-dropdown-menu id="hidden-items">
    <aui-section label="Links">
        <aui-item-link href="https://example.com#profile">Profile</aui-item-link>
        <aui-item-link href="https://example.com#inbox">Inbox</aui-item-link>
        <aui-item-link hidden href="https://example.com#delete">Delete Profile</aui-item-link>
    </aui-section>
    <aui-section hidden label="Hidden Links">
        <aui-item-link href="https://example.com/#secret">Secret Page</aui-item-link>
    </aui-section>
</aui-dropdown-menu>

Dropdown triggers without arrows

On some occasions, it may be necessary to create a dropdown trigger without the arrow which is displayed by default. If this is required, you can add the aui-dropdown2-trigger-arrowless class to the trigger.

Demo code
Result
Profile Inbox Delete Profile
 
<button class="aui-button aui-dropdown2-trigger aui-dropdown2-trigger-arrowless" aria-controls="no-arrow-items">
    Trigger without arrow
</button>
 
<aui-dropdown-menu id="no-arrow-items">
    <aui-item-link href="https://example.com#profile">Profile</aui-item-link>
    <aui-item-link href="https://example.com#inbox">Inbox</aui-item-link>
    <aui-item-link href="https://example.com#delete">Delete Profile</aui-item-link>
</aui-dropdown-menu>

DOM placement

A dropdown will not alter its allocation in DOM tree by default.

To maintain a natural tab order for keyboard users, a dropdown should be rendered as the next sibling of its trigger.

It may happen that due to the design of your application the dropdown's content may get obscured - i.e. being clipped by the parent container with overflow:hidden; CSS property set.
You may want to modify your styles to avoid such behaviour and/or adjust the alignment of the dropdown .

In cases when such adjustments are not sufficient - you may specify a rendering DOM container.
Upon displaying the dropdown - the component will temporarily move it's subtree into the specified container - allowing for unobstructed rendering.
You should always choose the closest container allowing for unobstructed render.
You are responsible for ensuring the component is properly cleaned up, adequately to your application's lifecycle.

In order to specify a rendering DOM container, set the data-aui-dom-container attribute to a selector matching the container element:

Demo code
Result
Amazon Apple
 
<div id="dom-container">
    <aside>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Architecto consectetur eius enim laboriosam nulla quaerat, qui veniam. Adipisci amet architecto, deleniti dicta dolore esse in libero, mollitia perferendis placeat tempora!</aside>
    <section>
        <button class="aui-button aui-dropdown2-trigger" aria-controls="cropped">
            cropped
        </button>
        <aui-dropdown-menu id="cropped" data-aui-dom-container="#dom-container">
            <aui-section>
                <aui-item-link href="http://amazon.com">Amazon</aui-item-link>
                <aui-item-link href="http://apple.com">Apple</aui-item-link>
            </aui-section>
        </aui-dropdown-menu>
    </section>
</div>
  • If data-aui-dom-container attribute is set but the selector matches multiple elements - it will default to first available match.
  • If data-aui-dom-container attribute is set but the selector does not match to any existing elements it will default to document.body
  • If data-aui-dom-container attribute is not set, the dropdown will be left in place.

Ajax

Async dropdown

A dropdown can fetch its contents from a remote source which returns a JSON response matching the given specification.

To load contents from a remote source, set the src attribute to the URL of the remote endpoint.

Demo code
Result
 
<aui-dropdown-menu id="async-dropdown" src="/async-dropdown"></aui-dropdown-menu>

Server response

JSON specification

The remote endpoint must return a JSON response containing an array of objects representing sections and menu items. Each object must specify whether it is a section, link, checkbox, or radio button item using the type property:

Property Type Description
type String

The type of the dropdown item. Must be one of:

  • section
  • link
  • checkbox
  • radio

You may also provide additional properties, depending on the type of the item. Note that these properties closely mirror the attributes available in the markup API:

Item Type Property Type Description
section label String The label for a section. The object must have the type property set to section.
section items Array An array containing the child items of the section.
link for String The id of the aui-dropdown-menu submenu.
link href String The target URL of the link item.
link, checkbox, radio content String The text content of the item.
link, checkbox, radio disabled Boolean Sets the disabled property for the item.
link, checkbox, radio hidden Boolean Sets the hidden property for the item.
link, checkbox, radio interactive Boolean Sets the interactive property for the item.
checkbox, radio checked Boolean Sets the checked property for the item.

Example response

The core structure of this JSON is a list of sections, each section containing an optional label property and a mandatory items property.

The items array closely reflects the markup pattern – the type property corresponds to the component's tagname, and the attributes are listed as properties of the same name.

Boolean attributes must take a value of either true or false, otherwise the value of each property will be inserted into the corresponding attribute directly.

 
[
    { type: "section", label: "Projects", items: [
        { type: "link", href: "#aui", content: "AUI" },
        { type: "link", href: "#design-platform", content: "Design Platform" },
        { type: "link", href: "#adg", content: "ADG" }
    ]},
    { type: "section", label: "Issues", items: [
        { type: "link", href: "#aui-111", content: "AUI-111" },
        { type: "link", href: "#aui-222", disabled: true, content: "AUI-222" },
        { type: "link", href: "#aui-333", hidden: true, content: "AUI-333" }
    ]},
    { type: "section", label: "Checkboxes", items: [
        { type: "checkbox", interactive: true, content: "checkbox" },
        { type: "checkbox", interactive: true, checked: true, content: "checkbox checked" }
    ]},
    { type: "section", label: "Radio", items: [
        { type: "radio", interactive: true, content: "radio" },
        { type: "radio", interactive: true, checked: true, content: "radio checked" }
    ]}
]

API Reference

Dropdown trigger

<button>
Name Attribute Property Type Description
class="aui-dropdown2-trigger" is not an attribute is not a property String Add this class to <button> element to associate it as a dropdown trigger
aria-controls is an attribute is a property String The id of the dropdown that this button will open.
data-aui-alignment-container is an attribute is not a property String A selector matching the container element to use for alignment.

Dropdown menu

<aui-dropdown-menu>
Name Attribute Property Type Description
src is an attribute is a property String The URL of the remote source that returns a JSON response containing the dropdown contents to template.
data-aui-dom-container is an attribute is not a property String A selector matching the container element this dropdown should be appended to when opened.

Section

<aui-section>
Name Attribute Property Type Description
label is an attribute is a property String The text that will appear in the heading of a dropdown section.
class="aui-list-truncate" is not an attribute is not a property String Add this class to <aui-section> element to truncate its width to the width defined by the min-width and max-width styles.
<aui-item-link>
Name Attribute Property Type Description
for is an attribute is a property Boolean The id of another dropdown that this link will open as a submenu.
href is an attribute is a property Boolean The target URL of the link item.
disabled is an attribute is a property Boolean If set, the dropdown item will not be selectable by the user.
hidden is an attribute is a property Boolean If set, the dropdown item will not be visible.
interactive is an attribute is a property Boolean If set, the dropdown item will not close when clicked.
extra-classes is an attribute is a property String If set, space-delimited CSS classes provided in this attribute will be present in the underlying anchor element.

Checkbox item

<aui-item-checkbox>
Name Attribute Property Type Description
checked is an attribute is a property Boolean If set, the dropdown item will be selected.
disabled is an attribute is a property Boolean If set, the dropdown item will not be selectable by the user.
hidden is an attribute is a property Boolean If set, the dropdown item will not be visible.
interactive is an attribute is a property Boolean If set, the dropdown item will not close when clicked.

Radio item

<aui-item-radio>
Name Attribute Property Type Description
checked is an attribute is a property Boolean If set, the dropdown item will be selected.
disabled is an attribute is a property Boolean If set, the dropdown item will not be selectable by the user.
hidden is an attribute is a property Boolean If set, the dropdown item will not be visible.
interactive is an attribute is a property Boolean If set, the dropdown item will not close when clicked.

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.

Accessibility attributes

Avoid using submenus

Submenus are supported but should be avoided where possible.

Label

It is recommended to use label attribute to provide meaningful title for the dropdown menu sections (aui-section) in case there are several groups in one menu or there is a submenu.

Demo code
Result
Amazon Apple Facebook Google
Atlassian
Atlassian
 
<button class="aui-button aui-dropdown2-trigger" aria-controls="has-label">
    Dropdown labeled sections
</button>
​
<aui-dropdown-menu id="has-label">
    <aui-section label="All links">
        <aui-item-link href="https://amazon.com">Amazon</aui-item-link>
        <aui-item-link href="https://apple.com">Apple</aui-item-link>
        <aui-item-link href="https://facebook.com">Facebook</aui-item-link>
        <aui-item-link href="https://google.com">Google</aui-item-link>
        <aui-item-link for="has-aria-label-and-submenu">Recently visited</aui-item-link>
     </aui-section>
     <aui-section label="Popular links">
        <aui-item-link href="https://atlassian.com">Atlassian</aui-item-link>
     </aui-section>
</aui-dropdown-menu>
​
<aui-dropdown-menu id="has-aria-label-and-submenu">
    <aui-section label="Recently visited">
        <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
    </aui-section>
</aui-dropdown-menu>

Recommendation

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