Dropdowns
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>
aria-controls
attribute to the id
of the dropown menu.
Result
<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>
- links,
- checkboxes, or
- radios.
To give a section a heading add the label
attribute:
<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>
Links
Use <aui-item-link>
href
attribute specified to add link items to a dropdown.
Result
<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>
Submenus
To add a submenu to a dropdown, create an <aui-dropdown-menu>
for
attribute of the
<aui-item-link>
id
of the
<aui-dropdown-menu>
<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>
Checkboxes
Use <aui-item-checkbox>
Result
<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>
Responding to events
Listen to change
events fired by
<aui-item-checkbox>
checked
attribute
to determine whether the item was checked or unchecked:
Result
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>
Result
<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>
Responding to events
Listen to change
events fired by the <aui-item-radio>
checked
attribute to differentiate between the two:
Result
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.');
}
}
});
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:
<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>
min-width
and max-width
styles to the <aui-dropdown-menu>
Options will be truncated to a single line matching the specified width:
Result
<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.
<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>
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.
Result
<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.
Result
<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:
<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 todocument.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.
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:
|
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
Name | Attribute | Property | Type | Description |
---|---|---|---|---|
class="aui-dropdown2-trigger" |
String | Add this class to <button> |
||
aria-controls |
String | The id of the dropdown that this button will open. | ||
data-aui-alignment-container |
String | A selector matching the container element to use for alignment. |
Dropdown menu
Name | Attribute | Property | Type | Description |
---|---|---|---|---|
src |
String | The URL of the remote source that returns a JSON response containing the dropdown contents to template. | ||
data-aui-dom-container |
String | A selector matching the container element this dropdown should be appended to when opened. |
Section
Name | Attribute | Property | Type | Description |
---|---|---|---|---|
label |
String | The text that will appear in the heading of a dropdown section. | ||
class="aui-list-truncate" |
String | Add this class to <aui-section> min-width and max-width styles. |
Link item
Name | Attribute | Property | Type | Description |
---|---|---|---|---|
for |
Boolean | The id of another dropdown that this link will open as a submenu. |
||
href |
Boolean | The target URL of the link item. | ||
disabled |
Boolean | If set, the dropdown item will not be selectable by the user. | ||
hidden |
Boolean | If set, the dropdown item will not be visible. | ||
interactive |
Boolean | If set, the dropdown item will not close when clicked. | ||
extra-classes |
String | If set, space-delimited CSS classes provided in this attribute will be present in the underlying anchor element. |
Checkbox item
Name | Attribute | Property | Type | Description |
---|---|---|---|---|
checked |
Boolean | If set, the dropdown item will be selected. | ||
disabled |
Boolean | If set, the dropdown item will not be selectable by the user. | ||
hidden |
Boolean | If set, the dropdown item will not be visible. | ||
interactive |
Boolean | If set, the dropdown item will not close when clicked. |
Radio item
Name | Attribute | Property | Type | Description |
---|---|---|---|---|
checked |
Boolean | If set, the dropdown item will be selected. | ||
disabled |
Boolean | If set, the dropdown item will not be selectable by the user. | ||
hidden |
Boolean | If set, the dropdown item will not be visible. | ||
interactive |
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.
<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.