docs/extension-test-page
What's New

Dropdown

Figma Storybook GitHub

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

Context Menu

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

Content Mode

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.

Vue API 

import { DtDropdown, DtDropdownSeparator } from '@dialpad/dialtone-vue';

Slots

Name
Type
anchor

Anchor element that activates the dropdown

footer

Slot for the footer content

list

Slot for the list component

Props

Name
Default
Type
appendTo
'body'
"'body'" | "'parent'" | "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.

  • "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.

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 true, the default trigger behavior will be disabled.

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.

Events

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

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.

Dropdown documentation last updated Thursday, June 18, 2026