Dropdown

A Dropdown presents a list of options or actions.

Preview

Usage

Use the Dropdown component when you have a list of links or actions that can be performed. Use the Select Menu component to allow the users to choose one option from the list.

The dropdown component provides accessibility controls when using with List item component.
The dropdown has two major pieces that are provided as required named slots: the anchor and the list.
The anchor slot contains the element that controls the dropdown's visibility.
The list slot contains a list of items to show as dropdown menu items.

Variants and Examples

Default

With Sections and Headings

<div>
  <div class="d-popover">
    <div id="DtPopover__anchor2">
      <button class="base-button__button d-btn d-btn--primary">
        <span class="d-btn__label base-button__label"> Click to open </span>
      </button>
    </div>
  </div>
</div>
<div class="tippy-box d-ps-absolute" data-tippy-root="" id="tippy-13" data-popper-placement="bottom" style="...">
  <div id="dt7" role="menu" aria-hidden="false" aria-labelledby="DtPopover__anchor8" aria-modal="false" class="d-popover__dialog d-popover__dialog--modal" tabindex="-1" style="...">
    <div class="d-popover__content">
      <ul id="dt6" class="d-dropdown-list d-py0">
        <ul id="dt16" class="d-list-item-group" role="group" aria-labelledby="dt16-heading">
          <li id="dt16-heading" role="presentation" class="dt-dropdown-list--header d-py4 d-px8 d-fw-semibold d-c-default">Menu Heading A</li>
          <li id="dt17" class="d-list-item d-list-item--static" tabindex="-1" role="listitem">
            <div class="d-item-layout">
              <section class="d-item-layout--content">
                <div class="d-item-layout--title">
                  Menu Item 1
                </div>
              </section>
            </div>
          </li>
          <li aria-hidden="true" class="d-list-item-separator"></li>
          <li id="dt18" class="d-list-item d-list-item--static" tabindex="-1" role="listitem">
            <div class="d-item-layout">
              <section class="d-item-layout--content">
                <div class="d-item-layout--title">
                  Menu Item 2
                </div>
              </section>
            </div>
          </li>
        </ul>
        <li aria-hidden="true" class="d-list-item-separator"></li>
        <ul id="dt19" class="d-list-item-group" role="group" aria-labelledby="dt19-heading">
          <li id="dt19-heading" role="presentation" class="dt-dropdown-list--header d-py4 d-px8 d-fw-semibold d-c-default">Menu Heading B</li>
          <li id="dt20" class="d-list-item d-list-item--static" tabindex="-1" role="listitem">
            <div class="d-item-layout">
              <section class="d-item-layout--content">
                <div class="d-item-layout--title">
                  Menu Item 3
                </div>
              </section>
            </div>
          </li>
        </ul>
      </ul>
    </div>
  </div>
</div>

Context Menu

Set openOnContext=true to open the menu on right-click (context menu) and disable the default trigger behavior.

 
<dt-dropdown navigation-type="arrow-keys" :open-on-context="true">
  <template #anchor="{ attrs }">
    <div
      v-bind="attrs"
      class="d-ba d-bas-dashed d-w264 d-py48 d-ta-center d-bgc-black-300"
    >
      Right click to open
    </div>
  </template>
  <template #list="{ close }">
    <dt-list-item
      v-for="(item) in items"
      :key="item.id"
      role="menuitem"
      navigation-type="arrow-keys"
      @click="close"
    >
      {{ item.name }}
    </dt-list-item>
  </template>
</dt-dropdown>

Vue API

Slots

Name	Description
anchor	Anchor element that activates the dropdown
footer	Slot for the footer content
list	Slot for the list component

Props

Name	Description	Default
appendTo	Sets the element to which the popover is going to append to. 'body' will append to the nearest body (supports shadow DOM). Type: HTML_ELEMENT_TYPE\|string Values: 'body''parent'HTMLElement	'body'
contentWidth	Width configuration for the popover content. When its value is 'anchor', the popover content will have the same width as the anchor. Type: string Values: nullanchor	null
fallbackPlacements	If the dropdown does not fit in the direction described by "placement", it will attempt to change it's direction to the "fallbackPlacements". Type: array Values: toptop-starttop-endrightright-startright-endleftleft-startleft-endbottombottom-startbottom-endautoauto-startauto-end	['auto']
listClass	Additional class for the wrapper list element. Type: string\|array\|object	''
listId	Sets an ID on the list element of the component. Used by several aria attributes as well as when deriving the IDs for each item. Type: string	function() { return getUniqueString(); }
maxHeight	Determines maximum height for the popover before overflow. Possible units rem\|px\|em Type: string	''
maxWidth	Determines maximum width for the popover before overflow. Possible units rem\|px\|%\|em Type: string	''
modal	Determines modal state, dropdown has a modal overlay preventing interaction with elements below it, but it is invisible. Type: boolean	true
navigationType	The type of navigation that this component should support. "arrow-keys" for items that are navigated with UP/DOWN keys. "tab" for items that are navigated using the TAB key. "none" for static items that are not interactive. Type: string Values: arrow-keystabnone	LIST_ITEM_NAVIGATION_TYPES.ARROW_KEYS
onBeginningOfList	A method that will be called when the selection goes past the beginning of the list. Type: func	null
onEndOfList	A method that will be called when the selection goes past the end of the list. Type: func	null
open	Controls whether the dropdown is shown. Leaving this null will have the dropdown trigger on click by default. If you set this value, the default trigger behavior will be disabled and you can control it as you need. Supports v-model Type: boolean	null
openOnContext	Opens the dropdown on right click (context menu). If you set this value to `true`, the default trigger behavior will be disabled. Type: boolean	false
padding	Vertical padding size around the list element. Type: string Values: nonesmalllarge	'small'
placement	The direction the dropdown displays relative to the anchor. Type: string	'bottom'
tether	If set to false the dialog will display over top of the anchor when there is insufficient space. If set to true it will never move from its position relative to the anchor and will clip instead. Popper.js docs Type: boolean Values: truefalse	true
transition	Named transition when the content display is toggled. Type: string	'fade'

Events

Name	Description
highlight	Event fired when the highlight changes Type: Number
keydown	Native keydown event Type: KeyboardEvent
opened	Event fired when dropdown is shown or hidden Type: Boolean \| Array
update:open	Event fired to sync the open prop with the parent component Type: undefined

Accessibility

A screen reader visible only close button is added by default.

The dropdown menu has a role of "menu" and the list items have a role "menuitem". See W3C guidelines for more information.

List

The Dropdown is rendered with semantic <ul> and <li>. The list slot is wrapped in <ul> element so make sure the items are wrapped in <li> element and each item has the menuitem role. It is recommended to use the List Item component as it supports all the necessary accessibility props and interactions.

Focus & Keyboard

A dropdown menu has well defined standard keyboard interactions that it should support. The focus will be set to the the active item on keyboard navigation. UP and DOWN arrows move the highlighted selection between the list items. HOME and END keys will jump straight to the first or the last item. Once the beginning or the end of the list is reached the selection will move to the opposite end of the list by default. If you want custom behavior you can pass onBeginningOfList and onEndOfList methods as props. A-Z keys will cycle through items that start with the corresponding letter.

Pressing ESC key while the dropdown has focus will emit an escape event and will close the menu. When the highlight selection changes, a highlight event is emitted with the index of the currently highlighted item. SPACE key will open the dropdown if it's closed and select the item when it's pressed on a list item.

Preview

Usage #

Variants and Examples #

Default #

With Sections and Headings #

Context Menu #

Vue API #

Slots

Props

Events

Accessibility #

List #

Focus & Keyboard #

Usage

Variants and Examples

Default

With Sections and Headings

Context Menu

Vue API

Accessibility

List

Focus & Keyboard