Show · Dropdown
Dropdown
A menu that pops down.

Demos

How to import

Basic Usage

Nested Usage

Users can nested Dropdown, which is suitable for situations with multiple sublevel options.

Element Properties

By configuing disabled for Dropdown.Item, you can disabled an item.
By configuring type on Dropdown.Item, you can display text in different colors.
By configuring icon on Dropdown.Item (icon needs to be ReactNode), you can quickly configured icon of item.
The position of support is the same. Tooltip, commonly used are: "bottom", "bottomLeft", "bottomRight".

Trigger Mode

The default is the move-in Trigger, which can be expanded by getting focus, clicking, or customizing the event trigger menu.

Trigger Event

Click on the menu item to trigger different mouse events, support onClick, onMouseEnter, onMouseLeave and onContextMenu.

Group Combinations

Combination usesDropdown.Title, Dropdown.Divider, Dropdown.Item.
Configure type Dropdown.Item to show different colors of text.

Json Usage

Can use the menu attribute to configure the Dropdown content menu

API Reference

PropertiesInstructionsTypeDefaultVersion
autoAdjustOverflowWhether the pop-up layer automatically adjusts its direction when it is blockedbooleantrue
classNameclassname of the outer style of the pop-up layerstring
closeOnEscWhether to close the panel by pressing the Esc key in the trigger or popup layer. It does not take effect when visible is under controlledbooleantrue2.13.0
childrenChild elements wrapped by the drop layerReactNode
clickToHideWhether to close the drop-down layer automatically when clicking on the drop-down layerboolean0.24.0
contentClassNameDrop-down menu root element class namestring
keepDOMWhether to keep the internal component DOM from being destroyed when closingbooleanfalse2.31.0
getPopupContainerSpecifies the parent DOM, and the bullet layer will be rendered to the DOM, you need to set 'position: relative` This will change the DOM tree position, but not the view's rendering position.function():HTMLElement() => document.body
marginPopup layer calculates the size of the safe area when the current direction overflows, used in scenes covered by fixed elements, more detail refer to issue#549, same as Tooltip marginobject|number2.25.0
mouseEnterDelayAfter the mouse is moved into the Trigger, the display time is delayed, in milliseconds (only effective when the trigger is hover/focus)number50
mouseLeaveDelayThe time for the delay to disappear after the mouse moves out of the pop-up layer, in milliseconds (only effective when the trigger is hover/focus)number50
menuMenu content configArray<DropdownMenuItem>[]1.12.0
positionThe position of the pop-up menu, commonly used: 'bottom', 'bottomLeft', 'bottomRight', for more details, see Tooltip Positionstring'bottom'
renderContent of pop-up layer,include Dropdown.Menu Dropdown.ItemDropdown.TitleReactNode
rePosKeyYou can update the value of this item to manually trigger the repositioning of the pop-up layerstring | number
spacingThe distance between the pop-up layer and the children element, in pxnumber4
stylePop-up layer inline styleobject
showTickWhether to automatically display the checked tick on the left of the active Dropdown.Item itembooleanfalse0.26.0
stopPropagationWhether to prevent the click event on the pop-up layer from bubblingbooleanfalse0.34.0
triggerThe act of triggering a drop-down, optional 'hover', 'focus', 'click', 'custom'string'hover'
visibleDisplay the menu or not, need to be used with trigger customboolean
zIndexPop-up layer z-index valuenumber1050
onClickOutSideCallback when the pop-up layer is in the display state and the non-Children, non-floating layer inner area is clicked (only valid when trigger is custom, click)(e:event) => void2.1.0
onEscKeyDownCalled when Esc key is pressed in trigger or popup layerfunction(e:event)2.13.0
onVisibleChangeCallback when the pop-up layer display state changesfunction
PropertiesInstructionsTypeDefaultVersion
styleDrop-down menu styleobject0.28.0
classNameDrop-down menu style class namestring0.28.0
childrenThe child elements wrapped by the drop-down menu, usually Dropdown.Item or Dropdown.TitleReactNode
PropertiesInstructionsTypeDefaultVersion
activeWhether the current item is in the active state, there is a tick on the left when the active state is activated, the font is bold, and the color is deepened. When the showTick is false, even if the active is true, the tick will not be displayedbooleanfalse
classNameStyle class namestring
disabledDo you disable the menu?booleanfalse
iconIcon of DropdownItem, will be displayed on the leftReactNode1.16.0
styleInline styleobject
typeType, optional values: "primary","secondary", "tertiary", "warning", "danger"string"tertiary"
onClickClick the trigger callback eventfunction
onContextMenuThe callback event triggered by right clickfunction1.6.0
onMouseEnterA callback event triggered by MouseEnterfunction
onMouseLeaveThe callback event triggered by Mouse Leavefunction
PropertiesInstructionsTypeDefault
classNameStyle class namestring""
styleInline styleobject{}
PropertiesInstructionsType
nodemenu type: title,item,dividerstring
namemenu contentstring
Other Properties refer to Title、Item、Divider

Accessibility

ARIA

  • Dropdown.Menu role is set to menu, aria-orientatio is set to vertical
  • Dropdown.Item role is set to menuitem

Keyboard and Focus

  • Dropdown triggers can be focused, currently supports 3 triggering methods:
    • When the trigger method is set to hover or focus: the Dropdown is opened when the mouse is hovering or focused. After the Dropdown is opened, the user can use the Down Arrow to move the focus to the Dropdown
    • When the trigger method is set to click: Use the Enter or Space key to open the Dropdown when clicking the trigger or focusing, and the focus will automatically focus on the first non-disabled item in the Dropdown
  • When the focus is on the menu item inside the Dropdown:
    • Keyboard users can use the keyboard Up Arrow or Down Arrow to switch between interactable elements
    • Use the Enter key or the Space key to activate the focused menu item, if the menu item is bound to onClick, the event will be fired
  • Keyboard users can close the Dropdown by pressing Esc, after which the focus returns to the trigger
  • Keyboard interaction does not yet fully support nested scenes

Content Guidelines

  • The content of the options in the drop-down box needs to be expressed accurately and contain information to make it easier for users to choose among the options when browsing
  • Use statement-like capitalization and write options concisely and clearly
  • In the case of an action option, use a verb or verb phrase to describe the action that will occur when the user selects the option. For example, "Move", "Log time", or "Hide labels"
  • do not use prepositions
✅ Recommended usage❌ Deprecated usage

Design Tokens

FAQ

  • Why does the Dropdown layer accidentally wrap when the width is not enough near the screen border?
    After Chromium 104, the wrapping rendering strategy when the width of the screen border text is not enough has changed. For details, see issue #1022, the semi-side has been This problem was fixed in v2.17.0.