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.

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>
        <button type="button" class="dropdown-item active">Action</button>
        <button type="button" class="dropdown-item disabled">Disabled Link</button>
        <div class="dropdown-divider"></div>
        <button type="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">
                <button type="button" class="dropdown-item">Foo.</button>
                <div class="dropdown open right-top">
                    <button class="dropdown-item active expandable">Bar.</button>
                    <div class="dropdown-menu">
                        <button type="button" class="dropdown-item">Baz.</button>
                    </div>
                </div>
                <button type="button" class="dropdown-item">Foo 2.</button>
            </div>
        </div>
        <button type="button" class="dropdown-item">Ipsum.</button>
    </div>
</div>
2. Bottom-right
<div class="dropdown bottom-right open">
    <button type="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>
        <button type="button" class="dropdown-item active">First Action</button>
        <button type="button" class="dropdown-item disabled">Disabled Action</button>
        <div class="dropdown-divider"></div>
        <button type="button" class="dropdown-item">Link 1</button>
        <button type="button" class="dropdown-item">Link 2</button>
    </div>
</div>
3. Clarity icon as the dropdown toggle
<div class="dropdown bottom-left open">
    <button type="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>
        <button type="button" class="dropdown-item">Lorem.</button>
        <button type="button" class="dropdown-item">Lorem ipsum.</button>
        <button type="button" class="dropdown-item">Lorem ipsum dolor.</button>
        <div class="dropdown-divider"></div>
        <button type="button" class="dropdown-item">Action 1</button>
    </div>
</div>
<div class="dropdown open">
    <button type="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>
        <button type="button" class="dropdown-item">Lorem.</button>
        <button type="button" class="dropdown-item">Lorem ipsum.</button>
        <button type="button" class="dropdown-item">Lorem ipsum dolor.</button>
        <div class="dropdown-divider"></div>
        <button type="button" class="dropdown-item">Link</button>
    </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.

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 type="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">Dropdown header</label>
        <button type="button" clrDropdownItem>Action 1</button>
        <button type="button" disabled clrDropdownItem>Disabled Action</button>
        <div class="dropdown-divider"></div>
        <clr-dropdown>
            <button type="button" clrDropdownTrigger>Link 1</button>
            <clr-dropdown-menu>
                <button type="button" clrDropdownItem>Foo</button>
                <clr-dropdown>
                    <button type="button" clrDropdownTrigger>Bar</button>
                    <clr-dropdown-menu clrPosition="left-top">
                        <button type="button" clrDropdownItem>Baz</button>
                    </clr-dropdown-menu>
                </clr-dropdown>
            </clr-dropdown-menu>
        </clr-dropdown>
        <button type="button" clrDropdownItem>Link 2</button>
    </clr-dropdown-menu>
</clr-dropdown>
2. clrCloseMenuOnItemClick is set to false. Default is true.
<clr-dropdown [clrCloseMenuOnItemClick]="false">
    <button type="button" clrDropdownTrigger>
        <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">Dropdown header</label>
        <button type="button" clrDropdownItem>Action 1</button>
        <button type="button" clrDropdownItem>Action 2</button>
        <div class="dropdown-divider"></div>
        <button type="button" clrDropdownItem>Link 1</button>
        <button type="button" clrDropdownItem>Link 2</button>
    </clr-dropdown-menu>
</clr-dropdown>