Dropdowns¶

Usage¶

They consist of a dropdown toggle and an overlay containing the actions. The overlay is shown after clicking the dropdown toggle. Dropdown are available with text only or with text and icon.

When to use¶

• When there is a need for actions, which are related to each other (e.g. Export: PDF, Excel, Word, ...).
• When users need to make a choice among a list of mutually exclusive options.

Best practices¶

• Minimal button width is 100px.
• Menu container should be at least the same width as the button.

Design¶

Elements¶

1. Placeholder text, 2. Arrow, 3. Container, 4. menu container, 5. Icon (optional)

Variants¶

Interaction states are identical to the normal buttons.

Code¶

Use a button with the dropdown-toggle class as the trigger and place the content in a dropdown-menu. Add a dropdown-caret icon to indicate that the button opens an overlay.

The theme provides the dropdown styles. Use the CDK Overlay module to create, position, and dismiss the overlay. The CDK directives can also be used with content that does not use the dropdown-menu class.

Basic markup¶

Use a button for actions and an anchor for navigation. Set aria-expanded to the current open state and add show to the trigger while the overlay is open so that the caret rotates.

<button
  #trigger="cdkOverlayOrigin"
  type="button"
  class="btn btn-primary dropdown-toggle"
  cdkOverlayOrigin
  [class.show]="open()"
  [attr.aria-expanded]="open()"
  (click)="open.set(true)"
>
  Actions
  <si-icon class="dropdown-caret icon" icon="element-down-2" />
</button>

<ng-template
  cdkConnectedOverlay
  cdkConnectedOverlayBackdropClass="cdk-overlay-transparent-backdrop"
  [cdkConnectedOverlayOpen]="open()"
  [cdkConnectedOverlayOrigin]="trigger"
  [cdkConnectedOverlayHasBackdrop]="true"
  (backdropClick)="open.set(false)"
  (detach)="open.set(false)"
>
  <div class="dropdown-menu position-static d-block">
    <button type="button" class="dropdown-item">Edit</button>
    <button type="button" class="dropdown-item">Duplicate</button>
    <div class="dropdown-divider"></div>
    <button type="button" class="dropdown-item">Delete</button>
  </div>
</ng-template>

The open state controls the overlay. Use a transparent backdrop to close it when the user clicks outside. Also update the state on (detach), which is emitted when the overlay closes, including after pressing Escape. The position-static and d-block utility classes allow the CDK to position the rendered menu.

For having a proper keyboard interaction, we are using the CDK Focus trap. It ensures that the focus will remain within the overlay while it is open. Enabling [cdkTrapFocusAutoCapture]="true" ensures, that the focus will be moved into the overlay on creation and returned to the trigger when the overlay is closed.

Directions¶

Wrap the trigger and menu in one of the direction classes to place a statically positioned menu relative to its trigger. The caret direction changes automatically.

<div class="dropend">
  <button type="button" class="btn btn-secondary dropdown-toggle">
    More actions
    <si-icon class="dropdown-caret icon" icon="element-down-2" />
  </button>
  <div class="dropdown-menu show">
    <button type="button" class="dropdown-item">Action</button>
  </div>
</div>

When using the CDK Overlay, configure the connected overlay positions instead. The direction classes are useful for menus that remain in the document flow or when the position is managed by the application.

Alignment¶

Use an alignment class on the dropdown-menu to align it with its trigger. align-start is the default placement.

<div class="dropdown">
  <button type="button" class="btn btn-secondary dropdown-toggle">Actions</button>
  <div class="dropdown-menu show align-end">
    <button type="button" class="dropdown-item">Action</button>
  </div>
</div>

Menu content¶

Use dropdown-item for interactive actions. It supports the active and disabled states. Use dropdown-item-text for non-interactive content and dropdown-header to label a group of items. Use dropdown-divider to separate related groups.

<div class="dropdown-menu show">
  <div class="dropdown-header">Export</div>
  <button type="button" class="dropdown-item active">PDF</button>
  <button type="button" class="dropdown-item">Excel</button>
  <button type="button" class="dropdown-item" disabled>Word</button>
  <div class="dropdown-divider"></div>
  <div class="dropdown-item-text">Exports include the current filters.</div>
</div>

For items with icons, place the icon before an item-title. A trailing menu-end-icon can communicate an additional state or a follow-up action.

<button type="button" class="dropdown-item">
  <si-icon class="icon" icon="element-download" />
  <span class="item-title">Download</span>
  <si-icon class="menu-end-icon icon" icon="element-right-2" />
</button>

Long menus¶

dropdown-menu scrolls when its height exceeds the viewport. Add dropdown-menu-scroller to apply the recommended bounded height for menus with many items.

<div class="dropdown-menu dropdown-menu-scroller show">
  <!-- Dropdown items -->
</div>

Related components¶

Use button groups to create split-button patterns. Use the menu component when the content, see content actions.

CdkConnectedOverlay API Documentation¶

Directive to facilitate declarative creation of an Overlay using a FlexibleConnectedPositionStrategy.

Input Properties¶

Output Properties¶

Attributes and Methods¶

CdkOverlayOrigin API Documentation¶

Directive applied to an element to make it usable as an origin for an Overlay using a ConnectedPositionStrategy.

Attributes and Methods¶

CdkTrapFocus API Documentation¶

Directive for trapping focus within a region.

Input Properties¶

Attributes and Methods¶

Types Documentation¶

No types to document for items on this page.