Documentation

Dropdown2

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.

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.

Status

Examples

Code

HTML

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.

Simple dropdown

Trigger:

<a href="#dwarfers" aria-owns="dwarfers" aria-haspopup="true" class="aui-dropdown2-trigger">Dropdown trigger</a>

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.

Dropdown:

<div id="dwarfers" class="aui-dropdown2">
    <ul class="aui-list-truncate">
        <li><a href="#">Menu item</a></li>
        <li><a href="#">Menu item</a></li>
        <li><a href="#">Menu item</a></li>
        <li><a href="#">Menu item</a></li>
    </ul>
</div>

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:

<button class="aui-button aui-dropdown2-trigger aui-dropdown2-trigger-arrowless">

Dropdown with groups and headings

Dropdowns can have grouped items (visually this means they have a line between them), with an optional heading:

<div id="red-dwarf-ships" class="aui-dropdown2">
    <div class="aui-dropdown2-section">
        <ul>
            <li><a href="#foo">Red Dwarf</a></li>
            <li><a href="#foo">Low Red Dwarf</a></li>
            <li><a href="#foo">High Red Dwarf</a></li>
            <li><a href="#foo">Nanobot Red Dwarf</a></li>
        </ul>
    </div>
    <div class="aui-dropdown2-section">
        <div class="aui-dropdown2-heading">
            <strong>Support Ships</strong>
        </div>
        <ul>
            <li><a href="#foo">Starbug</a></li>
            <li><a href="#foo">Blue Midget</a></li>
            <li><a href="#foo">White Giant</a></li>
        </ul>
    </div>
    <div class="aui-dropdown2-section">
        <div class="aui-dropdown2-heading">
            <strong>Other Ships</strong>
        </div>
        <ul>
            <li><a href="#foo">Wildfire</a></li>
            <li><a href="#foo">SSS Esperanto</a></li>
            <li><a href="#foo">Nova 5</a></li>
        </ul>
    </div>
</div>

Dropdown width and truncation

The minimum and maximum widths of a dropdown container can be controlled with CSS:

#custom-width-example {
    min-width: 240px;
    max-width: 480px;
}

<div id="custom-width-example" class="aui-dropdown2">
    <ul class="aui-list-truncate">
        <li><a href="#short">Short label</a></li>
        <li><a href="#long">Especially long label that contains enough text to feed a walrus and also to cause this list item to flow over multiple lines</a></li>
    </ul>
</div>

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:

<div id="dropdown2-icons-wrap" class="aui-dropdown2">
    <ul>
        <li>
            <a href="http://example.com/" class="aui-icon-container">
                <span class="icon icon-example">Alt text</span> Icon span pattern 
            </a>
        </li>
        <li>
            <a href="http://example.com/" class="aui-icon-container">
                <img src="images/icon-test-16x16.png" alt="Alt text"> Icon as IMG element
            </a>
        </li>
        <li>
            <a href="http://example.com/" class="aui-icon-container icon-example">Icon as background image</a>
        </li>
    </ul>
</div>

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

<a href="URI" aria-owns="ID" aria-haspopup="true" aria-disabled="true" class="aui-dropdown2-trigger">Make me a sandwich</a>

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.

<div id="actions-menu" class="aui-dropdown2">
    <ul>
        <li><a href="./attachments#add-attachment-form">Attach file</a></li>
        <li><a href="#comment-form">Comment</a></li>
        <li><a class="disabled" title="You don't have permission to edit this issue.">Edit issue</a></li>
        <li><a href="./watchers">Watch issue</a></li>
    </ul>
</div>

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.

<li class="hidden">
    <a class="disabled" aria-disabled="true" href="http://example.com/">Comment</a>
</li>

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.

<div class="aui-dropdown2 aui-style-default">
    <div class="aui-dropdown2-section">
        <ul>
            <li><a class="aui-dropdown2-radio interactive checked">Option 1</a></li>
            <li><a class="aui-dropdown2-radio interactive">Option 2</a></li>
            <li><a class="aui-dropdown2-radio interactive">Option 3</a></li>
        </ul>
    </div>
    <div class="aui-dropdown2-section">
        <ul>
            <li><a id="spellcheck" class="aui-dropdown2-checkbox interactive">Check spelling while typing</a></li>
            <li><a class="aui-dropdown2-checkbox interactive checked disabled">Enable gravity</a></li>
        </ul>
    </div>
</div><!-- .aui-dropdown2 -->

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.

<ul class="aui-dropdown2-trigger-group">
    <li><a href="#foo" class="aui-dropdown2-trigger">Foo</a></li>
    <li><a href="#bar" class="aui-dropdown2-trigger">Bar</a></li>
    <li><a href="#sin" class="aui-dropdown2-trigger">Sin</a></li>
</ul>

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 aligment based on something other than the viewport.

To do that, set the optional data-container attribute on the trigger, with a jQuery selector (usually an ID or class):

<a href="URI" aria-owns="ID" aria-haspopup="true" class="aui-dropdown2-trigger" data-container="JQUERYSELECTOR">Text</a>

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':

<a href="#dropdownid" aria-owns="#dropdownid" aria-haspopup="true" class="aui-dropdown2-trigger" data-container="#container">Text</a>

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.

<a ... data-dropdown2-hide-location="hidemehere">Trigger</a>
<div id="hidemehere">Dropdown will be placed here when hidden.</div>

Programmatically showing or hiding a dropdown

To programmatically open a dropdown menu, dispatch an "aui-button-invoke" jQuery event on the dropdown trigger element:

AJS.$("#myTrigger").trigger("aui-button-invoke");

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.

AJS.$("#myDropdown").on({
    "aui-dropdown2-show": function() {
      $dd.addClass("loading");
      $.get("/actions/myDropdown", function(responseHTML) {
          $dd.removeClass("loading");
          $dd.html(responseHTML);
          $dd.find("a").first().addClass("active"); // Remember to select an option!
      });
    },
    "aui-dropdown2-hide": function(event) {
      $dd.empty();
    }
});

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:

AJS.$("#spellcheck").on({
    "aui-dropdown2-item-check": function() {
        SpellChecker.enable();
        SpellChecker.run();
    },
    "aui-dropdown2-item-uncheck": function() {
        SpellChecker.disable();
    }
});