A dropdown menu allows the user to choose an option or action from a contextual list. The source of the dropdown is usually a button.
Dropdown menu styles

Description

  • Default line height is 30 px; 36 px for x-small breakpoint (<544px) touch targets
  • Headers and or dividers may be used to organize a longer list of items
  • Menu width: Minimum 168 px; Maximum 336 px
  • Items in the list have hover and click states

Dropdown menus present a list of options that take an immediate action or navigate the user outside of the current context.

vs

Select boxes present a list of options that the user can choose from and apply to an input field.

Behavior

  • Clicking on the toggle opens the dropdown
  • By default, selecting a menu item or clicking outside the menu dismisses the menu. You can change this behavior to keep the menu open on item selection

Placement

By default, a dropdown opens from the bottom of the toggle, along the left side. You can change the placement by using one of the eight direction classes.

Dropdown menu placement

Recommendations

  • Use a button for the toggle. The button can contain either text or an icon
  • Order menu items by usage, except for destructive actions, which belong at the bottom
  • Keep the text short and concise. Long menu items are truncated from the end and an ellipsis added
  • Nested menus may be used to organize long lists of items into categories
  • Limit menus to three levels: Root menu plus up to two levels of nested menus
  • Disable a menu item if:
    • It can apply in a different context
    • The user doesn’t have permissions for the action
    • An applicable object is not currently selected

Nested Menu

Nested menus are an extension of dropdown menus. They save screen space by organizing a long list of items into categories that the user can click to reveal deeper levels.

Description

  • Same visual style as standard dropdown menu with the exception of a darker border (#9A9A9A)
  • Slight overlap (4px) over root menu to emphasize stack order
  • Width: Minimum 168 px; Maximum 336 px
  • Default line height is 30 px; 36 px for x-small breakpoint (<544px)

Interaction

  • With mouse: Click group name to reveal nested menus. Group name stays in selected state to serve as a breadcrumb
  • Clicking outside of the menu dismisses all menus
Dropdown nested menu

Placement

Dropdown nested menu
Default placement and stack order

By default a nested menu pops up on the right side of its root menu.

Dropdown nested menu
Small screen / responsive placement and stack order (<544px)

If screen space isn’t available to the right of the root menu, the nested menu appears on the left side. If there is a second nested menu, it appears to the right of the first nested menu, creating a zig-zag pattern.

Accessibility

Clarity static (HTML/CSS) component does not come pre-baked with all the necessary ARIA attributes. The application developer should follow the guidelines below in their implementation.

Clarity Angular component follows these guidelines:

  • A dropdown menu should have an element with the role button that opens the menu.
  • The element with the button role should also have an aria-expanded attribute which is set to true when the dropdown menu is open.
  • The items should be inside an element with the role menu, and have the role menuitem.
  • If the menu uses headings, the heading should be used as an accessible description for each related item.
  • A visual element with role separator may be used between groups of items within a menu. The separator is not focusable or interactive.
  • An element that is not a menu item inside the menu should have the aria-hidden attribute set to true.
  • A menu item should not use the disabled attribute so disabled items can be focusable. Instead, use [clrDisabled] to add the disabled visual style and ARIA attribute when needed. It is up to the application to ensure that the disabled item is not activatable.

Keyboard Interaction

Enter, Space, Down Arrow on the menu buttonOpens the menu and focuses on the first item
Up Arrow on menuFocus on the previous item, or the last item if currently on the first one
Down Arrow on menuFocus on the next item, or the first item if currently on the first one
Right Arrow on a menu item with submenuOpens the submenu and focuses on the first item
Left Arrow on a submenuCloses the submenu and focuses on its parent item
EscCloses the menu and focuses on the trigger (in the case of submenu the trigger is its parent item).

Examples

1. Default dropdown (bottom-left):
<div class="dropdown open">
    <button class="dropdown-toggle btn btn-primary" type="button">
        Dropdown
        <clr-icon shape="caret down"></clr-icon>
    </button>
    <div class="dropdown-menu">
        <h4 class="dropdown-header">Dropdown header</h4>
        <div class="dropdown-item active">Action</div>
        <div class="dropdown-item disabled">Disabled Link</div>
        <div class="dropdown-divider" role="separator"></div>
        <button class="dropdown-item">Lorem.</button>
        <div class="dropdown open right-bottom">
            <button class="dropdown-item active expandable">Lorem ipsum.</button>
            <div class="dropdown-menu">
                <div class="dropdown-item">Foo.</div>
                <div class="dropdown open right-top">
                    <button class="dropdown-item active expandable">Bar.</button>
                    <div class="dropdown-menu">
                        <div class="dropdown-item">Baz.</div>
                    </div>
                </div>
                <div class="dropdown-item">Foo 2.</div>
            </div>
        </div>
        <button class="dropdown-item">Ipsum.</button>
    </div>
</div>
2. Bottom-right
<div class="dropdown bottom-right open">
    <button class="dropdown-toggle btn btn-primary">
        Dropdown
        <clr-icon shape="caret down"></clr-icon>
    </button>
    <div class="dropdown-menu">
        <h4 class="dropdown-header">Dropdown header</h4>
        <div class="dropdown-item active">First Action</div>
        <div class="dropdown-item disabled">Disabled Action</div>
        <div class="dropdown-divider"></div>
        <div class="dropdown-item">Link 1</div>
        <div class="dropdown-item">Link 2</div>
    </div>
</div>
3. Clarity icon as the dropdown toggle
<div class="dropdown bottom-left open">
    <button class="dropdown-toggle">
        <clr-icon shape="error" class="is-error" size="24"></clr-icon>
        <clr-icon shape="caret down"></clr-icon>
    </button>
    <div class="dropdown-menu">
        <h4 class="dropdown-header">Dropdown header</h4>
        <div class="dropdown-item">Lorem.</div>
        <div class="dropdown-item">Lorem ipsum.</div>
        <div class="dropdown-item">Lorem ipsum dolor.</div>
        <div class="dropdown-divider"></div>
        <div class="dropdown-item">Action 1</div>
    </div>
</div>
<div class="dropdown open">
    <button class="dropdown-toggle btn btn-link">
        Dropdown Toggle
        <clr-icon shape="caret down"></clr-icon>
    </button>
    <div class="dropdown-menu">
        <h4 class="dropdown-header">Dropdown header</h4>
        <div aria-label="Dropdown header Lorem" class="dropdown-item">Lorem.</div>
        <div aria-label="Dropdown header Lorem ipsum" class="dropdown-item">Lorem ipsum.</div>
        <div aria-label="Dropdown header Lorem ipsum dolor" class="dropdown-item">Lorem ipsum dolor.</div>
        <div class="dropdown-divider"></div>
        <div class="dropdown-item">Link</div>
    </div>
</div>

CSS classes

This class is a wrapper class around the .dropdown-toggle and th .dropdown-menu

Extend this class on a button, icon or text link clicking on which the dropdown menu will be activated

A required wrapper intended to contain the dropdown menu. Items in the menu should extend the .dropdown-header or .dropdown-item class. .dropdown-divider can be on a block element used to seperate item groups. .active class with .dropdown-item adds a different styling for selected elements. Add the .disabled class to dropdown items to style them as disabled.

.open:

A class to open the dropdown menu. Must be applied with .dropdown

The following classes when extended along with .dropdown will open the menu in the respective directions:

  • .bottom-left
  • .bottom-right
  • .top-left
  • .top-right
  • .left-bottom
  • .left-top
  • .right-top
  • .right-bottom

If used in one of the nested menus (that is, not the root level .dropdown), only the following classes are valid:

  • .bottom-left
  • .bottom-right
  • .top-left
  • .top-right

Angular Component

The dropdown component uses the *clrIfOpen structural directive (detailed documentation coming soon) on the menu to indicate clearly that the menu is only present in the DOM when open. We heavily recommend using it for many reasons: better performance, making the intent clear in your own templates, and following a more natural lifecycle for any directives or components inside of the menu.

If for some reason this behavior was not the one you wanted, we also support the dropdown menu without a *clrIfOpen directive on it. It will be created eagerly when the dropdown itself initializes, and will not be destroyed or recreated until the dropdown itself is. Please make sure you know exactly why you are omitting this directive if you end up doing so.

Summary of Options

<clr-dropdown> component
Input / OutputValuesDefaultEffect
[clrCloseMenuOnItemClick]
Type: Boolean
Default: true
BooleantrueIf true, the menu will close when a dropdown item is clicked
<clr-dropdown-menu> component
Input / OutputValuesDefaultEffect
[clrPosition]
Values:
Direction classnames
Default: "bottom-left"
CSS dropdown menu direction classnames. bottom-leftSets the direction in which the menu will open. If used in one of the nested menus, only four classes are valid: bottom-left, bottom-right, top-left, and top-right.
clrDropdownItem directive
Input / OutputValuesDefaultEffect
[clrDisabled]
Type: Boolean
Default: false
BooleanfalseIf true, the menu item will have disabled style and set the aria-disabled attribute to true.

Example

1. clrPosition is set to top-left. Default is bottom-left. For nested <clr-dropdown>, only the following positions are valid: bottom-left, bottom-right, top-left, top-right.
<clr-dropdown>
    <button class="btn btn-outline-primary" clrDropdownTrigger>
        Dropdown
        <clr-icon shape="caret down"></clr-icon>
    </button>
    <clr-dropdown-menu clrPosition="top-left" *clrIfOpen>
        <label class="dropdown-header" aria-hidden="true">Dropdown header</label>
        <div aria-label="Dropdown header Action 1" clrDropdownItem>Action 1</div>
        <div aria-label="Dropdown header Disabled Action" [clrDisabled]="true" clrDropdownItem>Disabled Action</div>
        <div class="dropdown-divider" role="separator" aria-hidden="true"></div>
        <clr-dropdown>
            <button clrDropdownTrigger>Link 1</button>
            <clr-dropdown-menu>
                <button clrDropdownItem>Foo</button>
                <clr-dropdown>
                    <button clrDropdownTrigger>Bar</button>
                    <clr-dropdown-menu clrPosition="left-top">
                        <button clrDropdownItem>Baz</button>
                    </clr-dropdown-menu>
                </clr-dropdown>
            </clr-dropdown-menu>
        </clr-dropdown>
        <div clrDropdownItem>Link 2</div>
    </clr-dropdown-menu>
</clr-dropdown>
2. clrCloseMenuOnItemClick is set to false. Default is true.
<clr-dropdown [clrCloseMenuOnItemClick]="false">
        <button clrDropdownTrigger aria-label="Dropdown demo button">
            <clr-icon shape="error" class="is-error" size="24"></clr-icon>
            <clr-icon shape="caret down"></clr-icon>
        </button>
        <clr-dropdown-menu *clrIfOpen>
            <label class="dropdown-header" aria-hidden="true">Dropdown header</label>
            <div aria-label="Dropdown header Action 1" clrDropdownItem>Action 1</div>
            <div aria-label="Dropdown header Action 2"  clrDropdownItem>Action 2</div>
            <div class="dropdown-divider" role="separator" aria-hidden="true"></div>
            <div clrDropdownItem>Link 1</div>
            <div clrDropdownItem>Link 2</div>
        </clr-dropdown-menu>
    </clr-dropdown>