Dropdown2

Ask a question
The Dropdown2 markup pattern has been deprecated in favor of using the dropdown menu web component.

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
Web resource key: com.atlassian.auiplugin:aui-dropdown2
AMD Module key: N/A
Experimental API: 4
General API: 5.1

Examples

Shipmates

The Crimson Short One

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:

  1. Set the aria-disabled attribute to "false" on the A
  2. Remove the disabled class from the A
  3. Remove the hidden class 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: