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

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

• links,
• checkboxes, or
• radios.

To give a section a heading add the label attribute:

Links

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

Submenus

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:

Checkboxes

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

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:

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:

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.

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:

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:

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

Dropdown menu

Section

Link item

Checkbox item

Radio item