Dropdown2 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.
Note while Dropdown v1 was extended and overridden in a huge variety of ways, Dropdown2 is specifically created to fill the use case of a dropdown menu - extensions and overrides are not supported.
|Included in AUI core?||Yes. You do not need to explicitly require the web resource key.|
|Web resource key:||
|AMD Module key:||N/A|
|General API status:||5.1|
There are two parts to the dropdown: the trigger and the actual dropdown. The dropdown can initially be included anywhere in the DOM – it will be appended to the body element when invoked (avoids stacking problems); and re-appended after the trigger when dismissed.
Triggers are paired with their dropdown using the aria-owns attribute, which must correspond to the ID of the dropdown.
aria-owns attribute must match the dropdown ID. The href should be either a hash link targeting the dropdown ID, or a URL to a relevant page. Both
aria-haspopup="true" and the class
aui-dropdown2-trigger must be present or the dropdown will not work.
If you need a dropdown trigger without an arrow you can specify an extra class:
Dropdowns can have grouped items (visually this means they have a line between them), with an optional heading:
The minimum and maximum widths of a dropdown container can be controlled with CSS:
An icon can be included in a Dropdown item by adding
class="aui-icon-container" to the item's
<a> element. The icon can be set with a
<span> (default pattern for icons),
<img> or as a background image with CSS:
You can disable an entire dropdown by adding
aria-disabled="true" to the trigger. You can enable it by setting
You can apply a disabled style to specific items within a dropdown by adding
class="disabled" to the item's A element. Ideally, the A element's href attribute should also be removed, although this is not strictly required. Note that this is a style only; you will need to disable any functionality you have attached to that item.
While not a recommended pattern, it is sometimes required to have a hidden item still present in a dropdown - to do this, add
class="hidden" to the LI element. To ensure this does not break keyboard navigation you must also disable the trigger within the item.
On load, Dropdown2 will automatically disable A elements inside LI.hidden elements (that is it will add
aria-disabled="true" and the disabled class to the A). If you need to hide an item after the dropdown has been opened you will need to set these attributes directly.
To reinstate the item, your code will have to do all of the following:
aria-disabledattribute to "false" on the A
disabledclass from the A
hiddenclass from the LI
While this is acknowledged as being a bit verbose, reinstating items after page load is not considered a common use case at this stage.
Checkboxes and radios can be added to a dropdown menu by using
class="aui-dropdown2-radio" on the A elements. The checked state of a checkbox or radio is indicated with
class="checked", and the unchecked state is indicated by the absence of this class. Radios are grouped by their containing UL element.
class="interactive" to an A element will prevent the dropdown container from hiding when an item is clicked. This is useful for checkboxes and radios so that the user can see the effect of their actions, but it can also be applied separately where needed.
Related dropdown menus can be grouped together in a toolbar by adding
class="aui-dropdown2-trigger-group" to a common ancestor of each dropdown trigger.
This adds extra interactions such as keyboard navigation between menus (left/right arrow keys); and grouped dropdowns opening by mouse hover after the first one is activated with a click.
Normally dropdowns align to the left or right based on the trigger's proximity to the edge of the viewport. That is, if it's too close to the right, it will extend left instead. However in some scenarios (eg. fixed-width content designs, or dialogs) you may want a dropdown to decide alignment based on something other than the viewport.
To do that, set the optional
data-aui-alignment-container attribute on the dropdown, with a jQuery selector (usually an ID or class):
When the dropdown opens, it will compare its position to the closest instance of that jQuery selector.
For example, to contain dropdowns within a div with ID 'container':
From 5.0, by default a dropdown will be returned to its original location when hidden. You can also specify a custom "hide" location by adding a
data-dropdown2-hide-location attribute to the dropdown trigger. The attribute should specify the ID of the element where you want to hide your dropdown.
To programmatically open a dropdown menu, dispatch an "aui-button-invoke" jQuery event on the dropdown trigger element:
This is a toggle (for dropdown2 only), so if you dispatch "aui-button-invoke" on the trigger of an open dropdown, it will close.
jQuery events "aui-dropdown2-show" and "aui-dropdown2-hide" are dispatched on the dropdown container element when it is shown and hidden.
Event handlers aren't able to prevent the default action of "aui-dropdown2-show" and "aui-dropdown2-hide" events. Add
class="interactive" to the A elements that should not cause the dropdown to close when clicked.