Dropdown

A dropdown displays a list of links or actions for the user to choose from. It should not to be confused with a select element which is used in forms as a way for the user to select an option from a list.

When to use

• To display a list of actions under a single button toggle.

When not to use

• In forms. When providing more than 5–7 options in a form, use a Select instead.
• When selecting an option results in immediate navigation or update to the page content, use a Context Switcher (coming soon).

ToggleButton Size

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

Small

Medium

Chevron

Open toggles use a chevron pointing up, while closed toggles use a chevron pointing down.

Open

Closed

ToggleIcon

Chevrons indicate that ToggleIcon opens the list, so they’re required for all variations. The only (temporary) exception is the overflow menu, which uses the “more-horizontal” icon.

List

Placement

Right (default)

Left

List Size

Default width

The default List has a min-width of 200px and a max-width of 400px.

This means if there’s a list item with a lot of text (i.e., Description), the list will automatically expand up to 400px to accommodate the content of the widest list item.

• Account settings
• Sign out

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 do not recommend lists wider than 400px.

Manage

• Consul version v1.10.6
• Update Consul version
• Edit cluster
• Import to Terraform
• Copy and run this command in Terraform to import and manage this resource via our Terraform Provider
• Docs: Import usage
• terraform import hcp_connect
• Delete cluster

Height

The height of the list container is automatically determined based on the contents within the list.

Integrate with Terraform Cloud

• Integrate with Terraform Cloud
• Create a new run task in Terraform using the URL and key below.
• Endpoint URL
  https://api.cloud.hashicorp.com/
• HMAC Key
  91ee1e8ef65b337f0e70d793f456c71d
• Manage
• Regenrate HMAC key
• Integrating with Terraform Cloud
• About Terraform Cloud
• About Packer

ListItem Types

Icons

Icons in ListItems are optional.

We recommend letting the text speak for itself unless an icon provides additional value.

Ask yourself, “Which icon should I use here?” If the answer isn’t obvious within 5 seconds, consider whether the icon is really providing additional value.

More

• About
• About Consul
• Why Consul on HCP
• Success story
• Automate with Terraform
• Quick start a development cluster

Critical

While icons are optional, we recommend using a relevant icon for Critical ListItems. Using the right icon provides a stronger/more immediate visual indication that the action is destructive. See the section on color blind users and critical actions (internal link) for more details about making these actions more accessible.

• Rename
• Restore
• Delete

Content

General

We recommend using dropdowns only to display a list of links or actions. A dropdown should not be a catch-all used to squeeze a lot of content into a small, contained area. A crowded dropdown is difficult for the user to parse and can result in a poor user experience.

If you find that you need additional custom content in the dropdown, please reach out to the HDS team (internal link) to discuss alternative options.

ListItems

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

How to use this component

To make the invocation more intuitive for developers, we’ve provided contextual components for toggles and list items. For example, <Hds::Dropdown::ListItem::Separator /> is yielded in a hash, using the key <XX.Separator /> when invoked:

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

ListItem::Interactive

The Interactive list item renders the correct element based on the passing of an @route, @href, or the addition of a click event (i.e., {{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 a @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)

If you pass a @route, Ember’s <LinkTo> will be used:

{{!-- 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>

If the route is external to your current engine, you must also pass @isRouteExternal=true to the component so that it will use <LinkToExternal> instead of a <LinkTo>. For more details see the Hds::Interactive component documentation.

All the standard arguments for the <LinkTo/LinkToExternal> components are supported (eg. models/model/query/current-when/replace).

Examples

ToggleButton + ListItem, Separator

This example shows a dropdown with a toggle-button, links, a separator and a link (color, critical):

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

Rendered (positioned to the right):

ToggleButton + Title, Description, CopyItem, Separator

This example demonstrates the use of a dropdown with a toggle-button (color, secondary), title, description, a generic (which is yielding a Link::Standalone component), copy-item, a separator and a link (color, critical):

To indicate that a secondary button style should be used for the "button" toggle, add @color="secondary". If no @color is declared, primary will be used by default.

<Hds::Dropdown as |dd| >
  <dd.ToggleButton @text="Integrate with Terraform Cloud" @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>

ToggleIcon for "overflow" dropdown menus

Example: an "overflow" toggle for use only in a table element (per design). The dropdown has default and destructive (critical) links. This is the only use case where it is acceptable to use @hasChevron=false.

Note that toggleText is still required–it provides the aria-label for the toggle button.

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

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., checking asynchronously the user’s permission to execute a certain operation, once the toggle has been clicked).

In that case the argument @isLoading=true can be passed to the item: this will show a "loading" icon (even if an argument @icon is provided) and set 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>

ToggleIcon as user menu

In this example, we have a user icon with a title, description, separator, and links.

Note that toggleText is still required, because it supplies the aria-label for the toggle button.

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

Rendered as a toggle/icon for a user menu (positioned to the right):

Here is a customized example to demonstrate how that would look like in dark mode (not supported by the design system yet):

ToggleIcon with other icons

In this example, we have a settings icon with a title, description, separator, and links.

Note that toggleText is still required, because it supplies the aria-label for the toggle button.

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

Component API

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

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

Dropdown

Toggle::Button

Toggle::Icon

ListItem::CopyItem

ListItem::Description

ListItem::Generic

ListItem::Interactive

ListItem::Separator

ListItem::Title

Dropdown Anatomy

Toggle Anatomy

Button

Icon

ListItem Anatomy

CopyItem Anatomy

States

Button

Icon

• Hover
• Default
• Active
• Focus

• Default
• Hover
• Active
• Focus

ListItem

• Default
• Hover
• Active
• Focus
• Success

Conformance Rating

This component is conditionally conformant.

1. In any instance where data truncation occurs, there is no current method to access that data for the keyboard-only user.
2. If the chevron icon is removed from the dropdown’s toggle button, the component is no longer conformant.

Best Practices

Color blind users (specifically those with Achromatopsia) may have a hard time perceiving Critical ListItems within our dropdown. To provide a more accessible experience, we recommend:

• Using strong, clear language for the text (e.g., “Delete…”, “Revoke…”, etc.)
• Adding a relevant icon
• 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” (ie. showing a confirmation modal that requires the user to type “Delete” into a field before proceeding)

• Rename
• Restore
• Delete

Keyboard navigation

Many types of users rely on their keyboard to navigate the web, so it’s important that our designs have annotations for the focus order (how keyboard users navigate the web) to ensure we’re providing them with a natural path and great experience.

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, please let us know by submitting an issue.