Support Ships
Other Ships
Dropdown 2
Summary
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.
Dropdown2 is specifically created to fill the use case of a dropdown menu - extensions and overrides are not supported.
Status
| API status: | deprecated |
|---|---|
| Included in AUI core? | Yes. You do not need to explicitly require the web resource key. |
| Web resource key: |
com.atlassian.auiplugin:aui-dropdown2
|
| AMD Module key: | N/A |
| Experimental API: | 4 |
| General API: | 5.1 |
Examples
Code
Simple dropdown
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.
Trigger:
The 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.
Options
All Dropdown2 options are set via the markup, no JavaScript is required unless you wish to make use of events, or programmatically show and hide a dropdown.
Dropdown2 trigger without an arrow
If you need a dropdown trigger without an arrow you can specify an extra class:
Dropdown with groups and headings
Dropdowns can have grouped items (visually this means they have a line between them), with an optional heading:
Dropdown width and truncation
The minimum and maximum widths of a dropdown container can be controlled with CSS:
Dropdown with icons
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:
Disabled dropdowns
You can disable an entire dropdown by adding aria-disabled="true" to the trigger. You can enable it by setting aria-disabled="false".
Disabled dropdown items
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.
Hidden items
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:
- Set the
aria-disabledattribute to "false" on the A - Remove the
disabledclass from the A - Remove the
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, Radio Groups, Interactive Items
Checkboxes and radios can be added to a dropdown menu by using class="aui-dropdown2-checkbox" and 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.
Adding 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.
Dropdown menu groups/toolbars
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.
Control left/right alignment of dropdown by setting a custom container
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':
Controlling where the dropdown is hidden
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.
Programmatically showing or hiding a 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.
Events
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.
jQuery events "aui-dropdown2-item-check" and "aui-dropdown2-item-uncheck" are dispatched on checkbox and radio A elements. Event handlers can be added with JavaScript: