Dropdown

Toggleable menu for displaying lists of links and actions.

Basic usage

Hover on the dropdown menu to unfold it for more actions.

The triggering element is rendered by the default slot, and the dropdown part is rendered by the slot named dropdown. By default, dropdown list shows when you hover on the triggering element without having to click it.

Placement

Support 6 placements.

Set placement property to make dropdown appear in different locations.

vue

<template>
  <div class="flex flex-wrap items-center gap-4">
    <el-dropdown placement="top-start">
      <el-button> topStart </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2st</el-dropdown-item>
          <el-dropdown-item>The Action 3st</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="top">
      <el-button> top </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2st</el-dropdown-item>
          <el-dropdown-item>The Action 3st</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="top-end">
      <el-button> topEnd </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2st</el-dropdown-item>
          <el-dropdown-item>The Action 3st</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom-start">
      <el-button> bottomStart </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2st</el-dropdown-item>
          <el-dropdown-item>The Action 3st</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom">
      <el-button> bottom </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2st</el-dropdown-item>
          <el-dropdown-item>The Action 3st</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
    <el-dropdown placement="bottom-end">
      <el-button> bottomEnd </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item>The Action 1st</el-dropdown-item>
          <el-dropdown-item>The Action 2st</el-dropdown-item>
          <el-dropdown-item>The Action 3st</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </div>
</template>

Triggering element

Use the button to trigger the dropdown list.

Use split-button to split the triggering element into a button group with the left button being a normal button and right one the actual triggering target. If you wanna insert a separator line between item three and item four, just add the divided attribute to item four.

How to trigger

Click the triggering element or hover on it.

Use the attribute trigger. By default, it is hover.

hover to trigger

click to trigger

right click to trigger

vue

<template>
  <el-row class="block-col-2">
    <el-col :span="8">
      <span class="demonstration">hover to trigger</span>
      <el-dropdown>
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
    <el-col :span="8">
      <span class="demonstration">click to trigger</span>
      <el-dropdown trigger="click">
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
    <el-col :span="8">
      <span class="demonstration">right click to trigger</span>
      <el-dropdown trigger="contextmenu">
        <span class="el-dropdown-link">
          Dropdown List<el-icon class="el-icon--right"><arrow-down /></el-icon>
        </span>
        <template #dropdown>
          <el-dropdown-menu>
            <el-dropdown-item :icon="Plus">Action 1</el-dropdown-item>
            <el-dropdown-item :icon="CirclePlusFilled">
              Action 2
            </el-dropdown-item>
            <el-dropdown-item :icon="CirclePlus">Action 3</el-dropdown-item>
            <el-dropdown-item :icon="Check">Action 4</el-dropdown-item>
            <el-dropdown-item :icon="CircleCheck">Action 5</el-dropdown-item>
          </el-dropdown-menu>
        </template>
      </el-dropdown>
    </el-col>
  </el-row>
</template>

<script lang="ts" setup>
import {
  ArrowDown,
  Check,
  CircleCheck,
  CirclePlus,
  CirclePlusFilled,
  Plus,
} from '@element-plus/icons-vue'
</script>

<style scoped>
.block-col-2 .demonstration {
  display: block;
  color: var(--el-text-color-secondary);
  font-size: 14px;
  margin-bottom: 20px;
}

.block-col-2 .el-dropdown-link {
  display: flex;
  align-items: center;
}
</style>

Use hide-on-click to define if menu closes on clicking.

By default menu will close when you click on menu items, and it can be turned off by setting hide-on-click to false.

Command event

Clicking each dropdown item fires an event whose parameter is assigned by each item.

You can open or close the dropdown menu by manually use handleOpen or handleClose

open(close) the Dropdown list2 will close(open) the Dropdown List1.

Sizes

Besides default size, Dropdown component provides three additional sizes for you to choose among different scenarios.

Use attribute size to set additional sizes with large, default or small.

Attributes

Name	Description	Type	Default
type	menu button type, refer to `Button` Component, only works when `split-button` is true	`enum`	''
size	menu size, also works on the split button	`enum`	''
button-props	props for the button component, refer to Button Attributes	`object`	—
max-height	the max height of menu	`string` / `number`	''
split-button	whether a button group is displayed	`boolean`	false
disabled	whether to disable	`boolean`	false
placement	placement of pop menu	`enum`	bottom
trigger	how to trigger	`enum`	hover
triggerKeys 2.9.1	specify whick keys on the keyboard can trigger when pressed	`array`	`['Enter', 'Space', 'ArrowDown', 'NumpadEnter']`
hide-on-click	whether to hide menu after clicking menu-item	`boolean`	true
show-timeout	delay time before show a dropdown (only works when trigger is `hover`)	`number`	150
hide-timeout	delay time before hide a dropdown (only works when trigger is `hover`)	`number`	150
role	the ARIA role attribute for the dropdown menu. Depending on the use case, you may want to change this to 'navigation'	`string`	menu
tabindex	tabindex of Dropdown	`number` / `string`	0
popper-class	custom class name for Dropdown's dropdown	`string`	''
popper-options	popper.js parameters	`object`	`{modifiers: [{name: 'computeStyles',options: {gpuAcceleration: false}}]}`
teleported 2.2.20	whether the dropdown popup is teleported to the body	`boolean`	true
persistent 2.9.5	when dropdown inactive and `persistent` is `false` , dropdown menu will be destroyed	`boolean`	true

Slots

Name	Description	Subtags
default	content of Dropdown. Notice: Must be a valid html dom element (ex. `<span>, <button> etc.`) or `el-component`, to attach the trigger listener	—
dropdown	content of the Dropdown Menu, usually a `<el-dropdown-menu>` element	Dropdown-Menu

Events

Name	Description	Type
click	if `split-button` is `true`, triggers when left button is clicked	`Function`
command	triggers when a dropdown item is clicked, the parameters is the command dispatched from the dropdown item	`Function`
visible-change	triggers when the dropdown appears/disappears, the param is true when it appears, and false otherwise	`Function`

Exposes

Method	Description	Type
handleOpen	open the dropdown menu	`Function`
handleClose	close the dropdown menu	`Function`

Slots

Name	Description	Subtags
default	content of Dropdown Menu	Dropdown-Item

Attributes

Name	Description	Type	Default
command	a command to be dispatched to Dropdown's `command` callback	`string` / `number` / `object`	—
disabled	whether the item is disabled	`boolean`	false
divided	whether a divider is displayed	`boolean`	false
icon	custom icon	`string` / `Component`	—