Dropdown

A dropdown is a flexible component that displays a list of actions or options to the user. It should not to be confused with Select, which is used in forms as a way for the user to make a selection from a list.

Usage

When to use

• To display a list of actions or links under a single button toggle.
• To allow singular or multiple selection outside of a form, such as within filtering.
• To provide the user with a way to easily switch context within the application.

When not to use

• In forms when providing the user with options to choose from, consider Select.

Toggle

Types

Toggles come in two variant types: button and icon.

Size

ToggleButtons come in two sizes: small and medium. This allows for placement in ButtonSets with buttons of the same size.

ToggleIcons come in two sizes: small and medium.

While we provide a small size variant, we recommend only using this for the Overflow menu within Tables because the icons and images start to become unrecognizable in smaller sizes.

Chevron usage

Open Toggles use icon chevron-up, while closed Toggles use chevron-down.

ToggleButtons require a visible chevron to indicate interactivity and provide distinction between Dropdowns and standard Buttons.

We strongly recommend providing visible chevrons on most instances of ToggleIcons to indicate interactivity. That said, it’s common to see ToggleIcons that use the more-horizontal icon without chevrons. Their placement, usually in the last column of a Table, is typically indicative of this type of interaction.

List

Placement

Lists can be positioned to the left or right of the Toggle, and above or below the Toggle to fit more appropriately within the UI. Lists do not currently have collision detection.

Size

Default width

Lists have a minimum width of 200px and a maximum width of 400px. This means if there’s a long string in a ListItem the List will automatically expand up to 400px to accommodate that content before the content wraps.

Fixed width

If you do not want the width of the List to expand automatically to accommodate the widest list item, you can indicate a specific width. As a best practice, we have set the maximum width to 400px.

Height

The height of the ListContainer is automatically determined based on the contents, but the height can also be set manually. We recommend setting the height manually if you know the list will be long.

ListItem

Types

Icon usage

Icons in ListItems are optional, and we recommend letting the text speak for itself unless an icon provides additional value.

We don’t recommend mixing and matching icon use; that’s to say, if using an icon in one ListItem, use an icon in all ListItems. Doing so keeps the text aligned so the eye can scan the list of options more easily.

Critical ListItems

Icons in Critical ListItems

While icons are optional, we recommend using a relevant icon for Critical ListItems. Using the correct icon provides a stronger and more immediate visual indication that the action is destructive. Read more about how color blind users see critical actions in our UIs.

Critical action patterns

We recommend adding a second confirmation layer after the user clicks “Delete” (e.g., showing a confirmation Modal that requires the user to type “Delete” into a field before proceeding). This safeguards against accidental clicks by requiring users to confirm the destructive action.

Content

There is no character limit for ListItems, but we recommend keeping them short and concise (~36 characters).

Take care to use dropdowns correctly. A crowded or overly complex dropdown can lead to a frustrating user experience, especially for assistive technology users. Contact the Design Systems Team to discuss alternative options if a dropdown feels too complex.

How to use this component

To make the invocation more flexible and intuitive, we provide contextual components for Toggles, ListItems, Header and Footer. For example, <Hds::Dropdown::ListItem::Separator /> would be contextually expressed as <dd.Separator />.

<Hds::Dropdown as |dd|>
  <dd.ToggleButton @text="Menu" />
  <dd.Title @text="Title Text" />
  <dd.Description @text="Descriptive text goes here." />
  <dd.Interactive @href="#" @text="Add" />
  <dd.Interactive @href="#" @text="Add More" />
  <dd.Interactive @href="#" @text="Add Another Thing Too" />
  <dd.Separator />
  <dd.Interactive @route="components" @icon="trash" @text="Delete" @color="critical" />
</Hds::Dropdown>

List position

By default, the list is positioned below the button, aligned to the right. To change the list position pass bottom-left, top-left, or top-right to @listPosition on the Dropdown component.

<Hds::Dropdown @listPosition="bottom-left" as |dd|>
  <dd.ToggleButton @text="Text Toggle" />
  <dd.Interactive @route="components" @text="Item One" />
  <dd.Interactive @route="components" @text="Item Two" />
  <dd.Interactive @route="components" @text="Item Three" />
  <dd.Interactive @text="Item Four (closes on click)" {{on "click" dd.close}} />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

In contexts where the Dropdown needs to be inline, to inherit the alignment from a parent, you can use the @isInline argument (and set the @listPosition accordingly to your needs):

<div class="doc-dropdown-mock-text-align-right">
  <Hds::Dropdown @isInline={{true}} @listPosition="bottom-right" as |dd|>
    <dd.ToggleButton @text="Text Toggle" @color="secondary" />
    <dd.Interactive @route="components" @text="Item One" />
    <dd.Interactive @route="components" @text="Item Two" />
    <dd.Interactive @route="components" @text="Item Three" />
  </Hds::Dropdown>
</div>

ToggleButton

The basic invocation of ToggleButton requires @text to be passed. By default, it renders a primary button with a chevron icon.

<Hds::Dropdown as |dd|>
  <dd.ToggleButton @text="Text Toggle" />
  <dd.Interactive @route="components" @text="Item One" />
  <dd.Interactive @route="components" @text="Item Two" />
  <dd.Interactive @route="components" @text="Item Three" />
  <dd.Interactive @text="Item Four (closes on click)" {{on "click" dd.close}} />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

Alternatively, pass secondary to @color to display a secondary button with a chevron icon.

<Hds::Dropdown as |dd|>
  <dd.ToggleButton @text="Text Toggle" @color="secondary" />
  <dd.Interactive @route="components" @text="Item One" />
  <dd.Interactive @route="components" @text="Item Two" />
  <dd.Interactive @route="components" @text="Item Three" />
  <dd.Interactive @text="Item Four (closes on click)" {{on "click" dd.close}} />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

ToggleIcon

ToggleIcon as overflow menu

Overflow menus are often found in the last column of a Tables. This is the only use case where it is acceptable to use @hasChevron=false. @text is still required, because it supplies the aria-label for ToggleIcon.

<Hds::Dropdown as |dd|>
  <dd.ToggleIcon @icon="more-horizontal" @text="Overflow Options" @hasChevron={{false}} />
  <dd.Interactive @route="components" @text="Create" />
  <dd.Interactive @route="components" @text="Read" />
  <dd.Interactive @route="components" @text="Update" />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

ToggleIcon as user menu

@text is still required, because it supplies the aria-label for ToggleIcon.

<Hds::Dropdown as |dd|>
  <dd.ToggleIcon @icon="user" @text="user menu" />
  <dd.Title @text="Signed In" />
  <dd.Description @text="email@domain.com" />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Settings and Preferences" />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

ToggleIcon with other icons

Pass any icon name to @icon to change the icon used in ToggleIcon. @text is still required, because it supplies the aria-label for ToggleIcon.

<Hds::Dropdown as |dd|>
  <dd.ToggleIcon @icon="settings" @text="settings menu" />
  <dd.Title @text="Signed In" />
  <dd.Description @text="email@domain.com" />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Settings and Preferences" />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

ListItem::Interactive

ListItem::Interactive renders the correct element based on the passing of an @route, @href, or the addition of a click event (e.g., {{on "click" this.myAction}}). Internally, the component uses the Hds::Interactive utility component.

Rendering a button

If you add an event handler (no @href or @route), a <button> element will be rendered:

{{!-- The Doc::ListContainer component is just to help the component render properly --}}
<Doc::ListContainer class="hds-dropdown__list">
  <Hds::Dropdown::ListItem::Interactive {{on "click" this.myAction}} @text="Run command" />
</Doc::ListContainer>

Rendering a link with @href

If you pass an @href argument, a link (<a> element) will be generated:

{{!-- The Doc::ListContainer component is just to help the component render properly --}}
<Doc::ListContainer class="hds-dropdown__list">
  <Hds::Dropdown::ListItem::Interactive @href="https://www.hashicorp.com/request-demo/terraform" @text="Request a demo" />
</Doc::ListContainer>

Rendering a LinkTo (with @route)

Pass a @route to render Ember <LinkTo>. If the route is external to your current engine, pass @isRouteExternal=true to use <LinkToExternal> instead of <LinkTo>. For more details see the Hds::Interactive component documentation. All the standard arguments for the <LinkTo/LinkToExternal> components are supported (e.g., models/model/query/current-when/replace).

{{!-- The Doc::ListContainer component is just to help the component render properly --}}
<Doc::ListContainer class="hds-dropdown__list">
  <Hds::Dropdown::ListItem::Interactive @route="my.page.route" @model="my.page.model" @text="Activate cluster" />
</Doc::ListContainer>

With a loading “interactive” item

There may be use cases when it’s necessary to put an item in a “loading” state while the app performs some operations (e.g., asynchronously checking the user’s permissions to execute a certain operation once the Toggle’s been clicked).

Pass the argument @isLoading=true to the item. This will show a “loading” icon (even if an argument @icon is provided) and sets the item as non-interactive until the value of @isLoading is set to false again.

<Hds::Dropdown as |dd|>
  <dd.ToggleIcon @icon="more-horizontal" @text="Overflow Options" @hasChevron={{false}} />
  <dd.Interactive @route="components" @isLoading={{true}} @text="Edit cluster" @color="action" @icon="edit" />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

ListItem::Generic

ListItem::Generic allows you to pass custom elements to the Dropdown.

<Hds::Dropdown as |dd|>
  <dd.ToggleButton @text="Text Toggle" @color="secondary" />
  <dd.Title @text="Integrate with Terraform Cloud" />
  <dd.Description @text="Create a new run task in Terraform using the URL and key below." />
  <dd.Generic>
    <Hds::Link::Standalone @text="Watch tutorial video" @icon="film" @href="/" />
  </dd.Generic>
  <dd.CopyItem @text="https://api.cloud.hashicorp.com" @copyItemTitle="Endpoint URL" />
  <dd.CopyItem @text="91ee1e8ef65b337f0e70d793f456c71d" @copyItemTitle="HMAC Key" />
</Hds::Dropdown>

Component API

The Dropdown component is composed of different child components each with their own APIs:

• The Dropdown component
  • Optional header and footer
• Toggle components to open/close the Dropdown
  • ToggleButton
  • ToggleIcon
• ListItem components, to build the Dropdown’s list items
  • Description
  • Generic
  • Interactive
  • Separator
  • Title

Dropdown

Dropdown::Header and Dropdown::Footer

If the Dropdown content exceeds the height of the container, the header and footer remain fixed while the list of items adjusts its height.

Toggle::Button

Toggle::Icon

ListItem::Interactive

ListItem::Title

ListItem::Description

ListItem::Separator

ListItem::CopyItem

ListItem::Checkmark

ListItem::Checkbox

ListItem::Radio

ListItem::Generic

Anatomy

Dropdown

Toggle

ListItem

States

Toggle

ListItem

Interactive

Checkbox

Checkmark

Radio

Conformance Rating

This component is conditionally conformant.

1. When truncation occurs, a keyboard-only user cannot access the truncated content.
2. The component is no longer conformant if the chevron icon is removed from the ToggleButton.

Known issues

ToggleIcon with no chevron

Setting @hasChevron to false on ToggleIcons doesn’t provide enough affordance; it’s not quickly seen as actionable.

Color blind users and critical actions

Color blind users, specifically those with Achromatopsia, may have a hard time perceiving Critical ListItems within our Dropdown component.

To provide a more accessible experience, we recommend:

• Using strong, clear language for the text (e.g., “Delete…”, “Revoke…”, etc.).
• Adding a relevant icon that indicates the action is destructive (e.g., trash).
• Moving the Critical ListItem to the bottom of the list or the section.
  • If at the bottom of a list, consider adding a separator above the Critical ListItem to help separate it from other ListItems.
• Adding a second confirmation layer after the user clicks “Delete” (e.g., showing a confirmation Modal that requires the user to type “Delete” into a field before proceeding).

Keyboard navigation

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.