Usage

• 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

A dropdown menu is a contextual list that allows the user to choose an option that take an immediate action or navigate the user to another view. The source of the dropdown is usually a button.

Dropdown vs Select

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

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.

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

• 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

Placement

Default placement and stack order

By default a nested menu pops up on the right side of its root 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 (opens new window). 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 (opens new window).

Interaction

Enter, Space, Down Arrow on the menu button	Opens the menu and focuses on the first item
Up Arrow on menu	Focus on the previous item, or the last item if currently on the first one
Down Arrow on menu	Focus on the next item, or the first item if currently on the first one
Right Arrow on a menu item with submenu	Opens the submenu and focuses on the first item
Left Arrow on a submenu	Closes the submenu and focuses on its parent item
Esc	Closes the menu and focuses on the trigger (in the case of submenu the trigger is its parent item).

Code & Examples

Clarity UI Component

Default (bottom-left)

Dropdown header

Action

Disabled Link

Foo.

Baz.

Foo 2.

<div class="dropdown open">
  <button class="dropdown-toggle btn btn-primary" type="button">
    Dropdown
    <cds-icon shape="caret" direction="down"></cds-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>

Bottom-right

Dropdown header

First Action

Disabled Action

Link 1

Link 2

<div class="dropdown bottom-right open">
  <button class="dropdown-toggle btn btn-primary">
    Dropdown
    <cds-icon shape="caret" direction="down"></cds-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>

Icon toggle

Dropdown header

Lorem.

Lorem ipsum.

Lorem ipsum dolor.

Action 1

<div class="dropdown bottom-left open">
  <button class="dropdown-toggle">
    <cds-icon shape="error" status="error" size="md"></cds-icon>
    <cds-icon shape="caret" direction="down"></cds-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>

CSS Classes

.dropdown

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

.dropdown-toggle

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

.dropdown-menu

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

Basic

Dropdown header

Action

Disabled Link

Foo.

Baz.

Foo 2.

<clr-dropdown>
  <button class="btn btn-outline-primary" clrDropdownTrigger>
    Dropdown
    <cds-icon shape="caret" direction="down"></cds-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>

Icon

Dropdown header

Lorem.

Lorem ipsum.

Lorem ipsum dolor.

Action 1

<clr-dropdown [clrCloseMenuOnItemClick]="false">
  <button clrDropdownTrigger aria-label="Dropdown demo button">
    <cds-icon shape="error" class="is-error" size="md"></cds-icon>
    <cds-icon shape="caret" direction="down"></cds-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>