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.
<dt-dropdown navigation-type="arrow-keys"> <template #anchor="{ attrs }"> <dt-button v-bind="attrs"> Click to open </dt-button> </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>
<dt-dropdown navigation-type="arrow-keys"> <template #anchor="{ attrs }"> <dt-button v-bind="attrs"> Click to open </dt-button> </template> <template #list="{ close }"> <dt-list-item-group heading-class="d-py-50 d-px-100 d-c-default d-fc-tertiary d-label--sm" heading="Menu Heading A" > <dt-list-item role="menuitem" navigation-type="arrow-keys" @click="close" > Menu Item 1 </dt-list-item> <dt-dropdown-separator /> <dt-list-item role="menuitem" navigation-type="arrow-keys" @click="close" > Menu Item 2 </dt-list-item> </dt-list-item-group> <dt-dropdown-separator /> <dt-list-item-group heading-class="d-py-50 d-px-100 d-c-default d-fc-tertiary d-label--sm" heading="Menu Heading B" > <dt-list-item role="menuitem" navigation-type="arrow-keys" @click="close" > Menu Item 3 </dt-list-item> </dt-list-item-group> </template> </dt-dropdown>
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-w-400 d-py-600 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>
Dropdown content renders outside the DOM tree. Use the contentMode prop to apply color mode (invert, light, dark) to the positioned content. See Positioned Components for details.
<dt-dropdown content-mode="invert">...</dt-dropdown> <dt-dropdown content-mode="dark">...</dt-dropdown> <dt-dropdown content-mode="light">...</dt-dropdown>
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.
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.
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.
import { DtDropdown, DtDropdownSeparator } from '@dialpad/dialtone-vue';
Name
|
Type
|
|---|---|
anchor | Anchor element that activates the dropdown |
footer | Slot for the footer content |
list | Slot for the list component |
Name
|
Default
|
Type
|
|---|---|---|
appendTo | 'body' |
"'body'"
|
"'parent'"
|
"'root'"
|
"HTMLElement"
|
""
Sets the element to which the popover is going to append to.
'body' will append to the nearest body (supports shadow DOM). |
contentMode |
"light"
|
"dark"
|
"invert"
Applies a color mode to the positioned content element. | |
contentWidth | null |
"null"
|
"anchor"
Width configuration for the popover content. When its value is 'anchor',
the popover content will have the same width as the anchor. |
fallbackPlacements | ['auto'] |
"top"
|
"top-start"
|
"top-end"
|
"right"
|
"right-start"
|
"right-end"
|
"left"
|
"left-start"
|
"left-end"
|
"bottom"
|
"bottom-start"
|
"bottom-end"
|
"auto"
|
"auto-start"
|
"auto-end"
If the dropdown does not fit in the direction described by "placement",
it will attempt to change it's direction to the "fallbackPlacements". |
footerClass | '' | string|array|object Additional class for the footer wrapper element. |
listClass | '' | string|array|object Additional class for the wrapper list element. |
listId | generated unique ID | string 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. |
maxHeight | '' | string Determines maximum height for the popover before overflow.
Possible units rem|px|em |
maxWidth | '' | string Determines maximum width for the popover before overflow.
Possible units rem|px|%|em |
modal | true | boolean Determines modal state, dropdown has a modal overlay preventing interaction with elements
below it, but it is invisible. |
navigationType | arrow-keys |
"arrow-keys"
|
"tab"
|
"none"
The type of navigation that this component should support. |
onBeginningOfList | null | func A method that will be called when the selection goes past the beginning of the list. |
onEndOfList | null | func A method that will be called when the selection goes past the end of the list. |
open | null |
"null"
|
"true"
|
"false"
Controls whether the dropdown is shown. When null (default), the dropdown
toggles on click. When set to true or false, the default trigger is
disabled and the parent controls visibility via v-model:open. |
openOnContext | false | boolean Opens the dropdown on right click (context menu). If you set this value to |
padding | 'small' |
"none"
|
"small"
|
"large"
Vertical padding size around the list element. |
placement | 'bottom' |
"top"
|
"top-start"
|
"top-end"
|
"right"
|
"right-start"
|
"right-end"
|
"left"
|
"left-start"
|
"left-end"
|
"bottom"
|
"bottom-start"
|
"bottom-end"
|
"auto"
|
"auto-start"
|
"auto-end"
The direction the dropdown displays relative to the anchor. |
tether | true |
"true"
|
"false"
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
|
transition | 'fade' | string Named transition when the content display is toggled. |
Name
|
Type
|
|---|---|
highlight | Number Event fired when the highlight changes |
keydown | KeyboardEvent Native keydown event |
opened | Boolean | Array Event fired when dropdown is shown or hidden |
update:open | undefined Event fired to sync the open prop with the parent component |
Dropdown documentation last updated Friday, September 4, 2026
fix/popover-modal-zindex-scope