Dropdown

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

• the dropdown component (parent to the child components)

• Toggle components to open/close the dropdown

  • ToggleButton
  • ToggleIcon

• And finally, list item components, to build the dropdown's list items

  • Description
  • Generic
  • Interactive
  • Separator
  • Title

Notice: to make the invocation more intuitive for developers, all the sub-components are named yields, so the yielded name is a simplified version of the full component name (eg. Hds::ListItem::Interactive becomes just Interactive). See below how they are invoked as yielded components.

Dropdown

Here is the API for the main ("container") component:

Toggle::Button

Here is the API for the "button-like" toggle component (yielded in a hash under the key ToggleButton):

Toggle::Icon

Here is the API for the icon-only toggle component (yielded as ToggleIcon):

ListItem::CopyItem

ListItem::Description

Here is the API for the "description" list item component (yielded in a hash under the key Description):

ListItem::Generic

Here is the API for the "generic" list item component (yielded in a hash under the key Generic):

ListItem::Interactive

Here is the API for the "interactive" list item component (yielded in a hash under the key Interactive):

ListItem::Separator

Here is the API for the "separator" list item component (yielded in a hash under the key Separator):

ListItem::Title

Here is the API for the "description" list item component (yielded in a hash under the key Title):

Invocation

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

<Hds::Dropdown as |dd|>
  <dd.ToggleButton @text="..." />
  <dd.Title @text="Lorem ipsum" />
  <dd.Description @text="Lorem ipsum dolor sine qua non est." />
  <dd.Interactive @href="..." @text="Add" />
  <dd.Separator />
  <dd.Interactive @route="components" @icon="trash" @text="Delete" @color="critical" />
</Hds::Dropdown>

URLs and routes handling

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}}).

Notice: the Interactive list item component internally uses the generic Hds::Interactive component. For more details about how this low-level component works please refer to its documentation page.

Basic use

If you don't pass a @href or @route argument a simple <button> will be generated:

<Hds::Dropdown as |dd|>
  ...
  <dd.Interactive {{on "click" this.myAction}} @text="Run command" />
</Hds::Dropdown>

Notice: in this case you will have to add your own event handling function to it.

With @href

If you pass a @href argument a <a> link will be generated:

<Hds::Dropdown as |dd|>
  ...
  <dd.Interactive @href="https://www.hashicorp.com/request-demo/terraform" @text="Request a demo" />
</Hds::Dropdown>

Important: when using the @href argument the component adds by default the attributes target="_blank" and rel="noopener noreferrer" to the <a> element (because this is the most common use case: internal links are generally handled using a @route argument). If the href points to an internal link, or uses a different protocol (eg. "mailto" of "ftp") you can pass @isHrefExternal=true to the component and it will not add the target and rel attributes (but you can pass yours if needed, using the ...attributes spreading. For more details see the Hds::Interactive component.

With @route

If you pass a @route argument a <a> link will be generated using a <LinkTo> Ember component:

<Hds::Dropdown as |dd|>
  ...
  <dd.Interactive @route="my.page.route" @model="my.page.model" @text="Activate cluster" />
</Hds::Dropdown>

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

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

Examples

ToggleButton + ListItem, Separator

This example demonstrates the use of 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>

Rendered as secondary variation (positioned to the right):

Notice: when using the "generic" list item the developer is completely responsible for any element yielded, including the accessibility of that element, as well as the layout of the content (we provide only the horizontal padding for consistency with the other items).

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, because it supplies 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>

Rendered in a table cell:

Column A

Column B

Column C

Row 1, cell 1

Row 1, cell 2

Row 2, cell 1

Row 2, cell 2

Row 3, cell 1

Row 3, cell 2

Row 4, cell 1

Row 4, cell 2

With a loading "interactive" item

Example: there may be use cases when it's necessary to put an item in a "loading" state while the app performs some operations (eg. 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>

Rendered in a table cell:

ID

Status

Cluster ABC

Running

Cluster XYZ

Idle

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="design-systems@hashicorp.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="design-systems@hashicorp.com" />
  <dd.Separator />
  <dd.Interactive @route="components" @text="Settings and Preferences" />
  <dd.Interactive @route="components" @text="Delete" @color="critical" @icon="trash" />
</Hds::Dropdown>

Rendered (positioned to the right):

Toggles

Toggle::Button

primary

Lorem ipsum

secondary

Lorem ipsum

primary small

Lorem ipsum

secondary small

Lorem ipsum

Toggle::Icon

with icon + chevron

icon only

with image (avatar)

States

primary/open:

Opened

secondary/open:

Opened

icon/open:

icon+chevron/open:

avatar+chevron/open:

---

List Items

Title / Description / Separator

default (min width)

• A simple title
• A description.
• Item

default (max width)

• A longer title that could span multiple lines if the characters surpass a certain length
• A longer description that could span on multiple lines if the number of characters require more width than the dropdown provides by default.
• A longer item that could span multiple lines if the characters surpass a certain length

fixed width

• A longer title that could span multiple lines if the characters surpass a certain length
• A longer description that could span on multiple lines if the number of characters require more width than the dropdown provides by default.
• A longer item that could span multiple lines if the characters surpass a certain length

Interactive

Generated element

default ⇒ <button>

• Lorem ipsum dolor

with @href ⇒ <a>

• Lorem ipsum dolor

with @route ⇒ <LinkTo> ⇒ <a>

• Lorem ipsum dolor

Colors

• action (default)

• critical

States (in each color)

Generic

• some generic content here

CopyItem

Content

base

• 91ee1e8ef65b337f0e70d793f456c71d

with copyItemTitle

• Lorem ipsum dolor
  91ee1e8ef65b337f0e70d793f456c71d

States

• success: 91ee1e8ef65b337f0e70d793f456c71d91ee1e8ef65b337f0e70d793f456c71d91ee1e8ef65b337f0e70d793f456c71d

When to use

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

When not to use

• In forms, when needing to select one or more options, use a Select
• When selecting an option results in immediate navigation or update to the page contentx, use a Context Switcher (coming soon)

Dropdown

Anatomy

Toggle

Required

List

Required, but only visible when open

Toggle

Anatomy

Button

Icon

States

Button

Icon

Banner (highlight): A note on disabled states: Because disabled states completely remove the interactive function of an element, it can be challenging for a user to understand why it has been disabled and/or why they cannot interact with that element. In an effort to avoid this confusion, we opt for using methods like enabling or hiding the element and, thus, are not offering a disabled state for the Dropdown Toggle. Read more about when to enable vs hide

Size

ToggleButtons come in a Medium and Small size to allow for placement in ButtonSets with buttons of the same size.

Medium

• Account settings
• Sign out

This component has been designed and implemented with accessibility in mind. When used as recommended, there should not be any accessibility issues with this component.

Known Potential Accessibility Issues

The following are known potential issues, and developers should keep these in mind when implementing this component:

1. In any instance where data truncation occurs, there is no current method to access that data for the keyboard-only user. Therefore, we do not recommend allowing data to be truncated within this component.
2. If the "overflow" toggle is used in the incorrect context, it will fail on perceivability. It must be used in in the current recommended context of a data table. For the best user experience, interactive elements should visually present as interactive, unless their context otherwise makes it clear that they are/should be interactive.

Applicable WCAG Success Criteria (Reference)

This section is for reference only. This component intends to conform to the following WCAG success criteria: