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.

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:

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

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:

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.

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:

Radios

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

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:

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:

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:

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.

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.

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.

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:

  • 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.

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.

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.

Recommendation

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