Dropdown

Ask a question

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

API status: experimental
Included in AUI core? Not in core You must explicitly require the web resource key.
Web resource key: com.atlassian.auiplugin:aui-dropdown2
AMD Module key: N/A
Experimental since: 5.9
Contents
  1. 1 Example
    1. 2 Behaviour
      1. 2.1 Sections
      2. 2.2 Links
      3. 2.3 Submenus
      4. 2.4 Checkboxes
      5. 2.5 Radios
      6. 2.6 Icons
    2. 3 Appearance
      1. 3.1 Alignment
      2. 3.2 Sizing
      3. 3.3 Disabled items
      4. 3.4 Hidden items
      5. 3.5 Dropdown triggers without arrows
    3. 4 Ajax
      1. 4.1 Async dropdown
      2. 4.2 Server response
    4. 5 API Reference
      1. 5.1 Dropdown menu
      2. 5.2 Section
      3. 5.3 Link item
      4. 5.4 Checkbox item
      5. 5.5 Radio item

    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.

    Example
    ​x
     
    <button class="aui-button aui-dropdown2-trigger" aria-controls="example-dropdown">
        Dropdown menu
    </button>
    ​
    <aui-dropdown-menu id="example-dropdown">
        <aui-section label="Links">
            <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
            <aui-item-link href="http://news.ycombinator.com">Hacker news</aui-item-link>
            <aui-item-link href="http://github.com">Github</aui-item-link>
        </aui-section>
        <aui-section label="Browsers">
            <aui-item-radio interactive checked>Chrome</aui-item-radio>
            <aui-item-radio interactive>Firefox</aui-item-radio>
            <aui-item-radio interactive disabled>Safari</aui-item-radio>
        </aui-section>
        <aui-section label="Languages">
            <aui-item-checkbox interactive checked>Javascript</aui-item-checkbox>
            <aui-item-checkbox interactive>Fortran</aui-item-checkbox>
            <aui-item-checkbox interactive>Rust</aui-item-checkbox>
        </aui-section>
    </aui-dropdown-menu>

    Behaviour

    Sections

    An <aui-section> is used to separate groups of related items, and may include a heading. They can contain a group of

    To give a section a heading add the label attribute:

    Example
     
    <aui-dropdown-menu id="sections-with-headings">
        <aui-section label="Favourites">
            <aui-item-link href="http://amazon.com">Amazon</aui-item-link>
            <aui-item-link href="http://apple.com">Apple</aui-item-link>
            <aui-item-link href="http://facebook.com">Facebook</aui-item-link>
            <aui-item-link href="http://google.com">Google</aui-item-link>
        </aui-section>
        <aui-section label="Recently visited">
            <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>

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

    Example
     
    <aui-dropdown-menu id="link-items">
        <aui-section label="Links">
            <aui-item-link href="http://example.com#profile">Profile</aui-item-link>
            <aui-item-link href="http://example.com#account-settings">Account settings</aui-item-link>
            <aui-item-link href="http://example.com#inbox">Inbox</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>

    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:

    Example
     
    <button class="aui-button aui-dropdown2-trigger" aria-controls="has-submenu">
        Dropdown with submenu
    </button>
    ​
    <aui-dropdown-menu id="has-submenu">
        <aui-section label="Links">
            <aui-item-link href="http://amazon.com">Amazon</aui-item-link>
            <aui-item-link href="http://apple.com">Apple</aui-item-link>
            <aui-item-link href="http://facebook.com">Facebook</aui-item-link>
            <aui-item-link href="http://google.com">Google</aui-item-link>
            <aui-item-link for="recently-visited">Recently visited</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>
    ​
    <aui-dropdown-menu id="recently-visited">
        <aui-section>
            <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>
    Avoid submenus where possible

    For usability reasons, submenus should be avoided where possible.

    Checkboxes

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

    Example
     
    <aui-dropdown-menu id="checkbox-items">
        <aui-section label="Languages">
            <aui-item-checkbox interactive checked>Javascript</aui-item-checkbox>
            <aui-item-checkbox interactive>Fortran</aui-item-checkbox>
            <aui-item-checkbox interactive>Rust</aui-item-checkbox>
        </aui-section>
    </aui-dropdown-menu>
    Use interactive with checkboxes and radios

    It's recommended to use the interactive boolean attribute on checkbox and radio items in dropdown menus to keep the dropdown open when users click those items.

    Disabling checkboxes and radios

    Add the disabled boolean attribute to checkbox and radio items to disable them.

    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:

    Example
     
    var dropdown = document.getElementById('is-checkbox-checked');
    dropdown.addEventListener('change', function (e) {
        var isChecked = e.target.hasAttribute('checked');
        if (isChecked) {
            console.log(e.target.textContent, 'was checked.');
        } else {
            console.log(e.target.textContent, 'was unchecked.');
        }
    });

    Radios

    Similar to checkboxes, use <aui-item-radio> elements to present a set of mutually exclusive options to the user:

    Example
     
    <aui-dropdown-menu id="radio-items">
        <aui-section label="Browsers">
            <aui-item-radio interactive checked>Chrome</aui-item-radio>
            <aui-item-radio interactive>Firefox</aui-item-radio>
            <aui-item-radio interactive>Safari</aui-item-radio>
        </aui-section>
    </aui-dropdown-menu>
    Group radio items with sections

    Only one radio item can be selected inside each section, so use an <aui-section> to group a set of <aui-item-radio> elements together.

    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:

    Example
     
    var section = document.querySelector('aui-section#browsers');
    section.addEventListener('change', function (e) {
        var tagName = e.target.tagName.toLowerCase();
        if (tagName === 'aui-item-radio') {
            if (e.target.hasAttribute('checked')) {
                console.log(e.target.textContent, 'was selected.');
            } else {
                console.log(e.target.textContent, 'was deselected.');
            }
        }
    });
    Order of radio change events is not guaranteed

    When a new radio is selected, the change event for the previously selected item being deselected may come before or after the event for the new item being selected, so it's best to examine the checked attribute to differentiate.

    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 to a selector matching the container element:

    Example
     
    <div id="alignment-container">
        <button class="aui-button aui-dropdown2-trigger" aria-controls="left-aligned">
            Left-aligned dropdown
        </button>
        <button class="aui-button aui-dropdown2-trigger" aria-controls="right-aligned">
            Right-aligned dropdown
        </button>
    </div>
    ​
    <aui-dropdown-menu id="left-aligned" data-aui-alignment-container="#alignment-container">
        <aui-section>
            <aui-item-link href="http://amazon.com">Amazon</aui-item-link>
            <aui-item-link href="http://apple.com">Apple</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>
    ​
    <aui-dropdown-menu id="right-aligned" data-aui-alignment-container="#alignment-container">
        <aui-section>
            <aui-item-link href="http://facebook.com">Facebook</aui-item-link>
            <aui-item-link href="http://google.com">Google</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>

    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:

    Example
     
    <aui-dropdown-menu id="has-min-width">
        <aui-section class="aui-list-truncate">
            <aui-item-link href="#short">Short label text</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>
    ​
    <aui-dropdown-menu id="has-max-width">
        <aui-section class="aui-list-truncate">
            <aui-item-link href="#long">
                Especially long label text that contains enough text to feed a walrus
                and also to cause this list item to flow over multiple lines
            </aui-item-link>
        </aui-section>
    </aui-dropdown-menu>
     
    #has-min-width {
        min-width: 300px;
    }
    #has-max-width {
        max-width: 100px;
    }

    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.

    Example
     
    <aui-dropdown-menu id="disabled-items">
        <aui-section label="Links">
            <aui-item-link href="http://atlassian.com">Atlassian</aui-item-link>
            <aui-item-link disabled href="http://google.com">Google</aui-item-link>
        </aui-section>
        <aui-section label="Browsers">
            <aui-item-radio interactive checked>Chrome</aui-item-radio>
            <aui-item-radio interactive>Firefox</aui-item-radio>
            <aui-item-radio disabled interactive>Safari</aui-item-radio>
        </aui-section>
        <aui-section label="Languages">
            <aui-item-checkbox interactive checked>Javascript</aui-item-checkbox>
            <aui-item-checkbox disabled interactive>Python</aui-item-checkbox>
        </aui-section>
    </aui-dropdown-menu>
    Disabled items don't prevent event listeners from firing

    Interacting with disabled items may still trigger any event listeners attached to the item itself, so ensure that you have also disabled any additional functionality attached to the item.

    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.

    Example
     
    <aui-dropdown-menu id="hidden-items">
        <aui-section label="Links">
            <aui-item-link href="http://example.com#profile">Profile</aui-item-link>
            <aui-item-link href="http://example.com#inbox">Inbox</aui-item-link>
            <aui-item-link hidden href="http://example.com#delete">Delete Profile</aui-item-link>
        </aui-section>
        <aui-section hidden label="Hidden Links">
            <aui-item-link href="http://example.com/#secret">Secret Page</aui-item-link>
        </aui-section>
    </aui-dropdown-menu>

    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.

    Example
     
    <button class="aui-button aui-dropdown2-trigger aui-dropdown2-trigger-arrowless" aria-controls="no-arrow-items">
        Trigger without arrow
    </button>
     
    <aui-dropdown-menu id="no-arrow-items">
        <aui-item-link href="http://example.com#profile">Profile</aui-item-link>
        <aui-item-link href="http://example.com#inbox">Inbox</aui-item-link>
        <aui-item-link href="http://example.com#delete">Delete Profile</aui-item-link>
    </aui-dropdown-menu>

    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.

    Example
     
    <aui-dropdown-menu id="async-dropdown" src="/async-dropdown"></aui-dropdown-menu>

    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:

    Property Type Description
    type String

    The type of the dropdown item. Must be one of:

    • section
    • link
    • checkbox
    • radio

    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:

    Item Type Property Type Description
    section label String The label for a section. The object must have the type property set to section.
    section items Array An array containing the child items of the section.
    link for String The id of the aui-dropdown-menu submenu.
    link href String The target URL of the link item.
    link, checkbox, radio content String The text content of the item.
    link, checkbox, radio disabled Boolean Sets the disabled property for the item.
    link, checkbox, radio hidden Boolean Sets the hidden property for the item.
    link, checkbox, radio interactive Boolean Sets the interactive property for the item.
    checkbox, radio checked Boolean Sets the checked property for the item.
    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.

     
    [
        { type: "section", label: "Projects", items: [
            { type: "link", href: "#aui", content: "AUI" },
            { type: "link", href: "#design-platform", content: "Design Platform" },
            { type: "link", href: "#adg", content: "ADG" }
        ]},
        { type: "section", label: "Issues", items: [
            { type: "link", href: "#aui-111", content: "AUI-111" },
            { type: "link", href: "#aui-222", disabled: true, content: "AUI-222" },
            { type: "link", href: "#aui-333", hidden: true, content: "AUI-333" }
        ]},
        { type: "section", label: "Checkboxes", items: [
            { type: "checkbox", interactive: true, content: "checkbox" },
            { type: "checkbox", interactive: true, checked: true, content: "checkbox checked" }
        ]},
        { type: "section", label: "Radio", items: [
            { type: "radio", interactive: true, content: "radio" },
            { type: "radio", interactive: true, checked: true, content: "radio checked" }
        ]}
    ]

    API Reference

    Dropdown menu

    <aui-dropdown-menu>
    Name Attribute Property Type Description
    src is an attribute is a property String The URL of the remote source that returns a JSON response containing the dropdown contents to template.
    data-aui-alignment-container is an attribute is not a property String A selector matching the container element to use for alignment.

    Section

    <aui-section>
    Name Attribute Property Type Description
    label is an attribute is a property String The text that will appear in the heading of a dropdown section.
    class="aui-list-truncate" is not an attribute is not a property String Add this class to <aui-section> element to truncate its width to the width defined by the min-width and max-width styles.
    <aui-item-link>
    Name Attribute Property Type Description
    for is an attribute is a property Boolean The id of another dropdown that this link will open as a submenu.
    href is an attribute is a property Boolean The target URL of the link item.
    disabled is an attribute is a property Boolean If set, the dropdown item will not be selectable by the user.
    hidden is an attribute is a property Boolean If set, the dropdown item will not be visible.
    interactive is an attribute is a property Boolean If set, the dropdown item will not close when clicked.

    Checkbox item

    <aui-item-checkbox>
    Name Attribute Property Type Description
    checked is an attribute is a property Boolean If set, the dropdown item will be selected.
    disabled is an attribute is a property Boolean If set, the dropdown item will not be selectable by the user.
    hidden is an attribute is a property Boolean If set, the dropdown item will not be visible.
    interactive is an attribute is a property Boolean If set, the dropdown item will not close when clicked.

    Radio item

    <aui-item-radio>
    Name Attribute Property Type Description
    checked is an attribute is a property Boolean If set, the dropdown item will be selected.
    disabled is an attribute is a property Boolean If set, the dropdown item will not be selectable by the user.
    hidden is an attribute is a property Boolean If set, the dropdown item will not be visible.
    interactive is an attribute is a property Boolean If set, the dropdown item will not close when clicked.