vant/packages/vant/src/dropdown-menu/README.md

DropdownMenu

Intro

The menu list that pops down downwards.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { DropdownMenu, DropdownItem } from 'vant';

const app = createApp();
app.use(DropdownMenu);
app.use(DropdownItem);

Usage

Basic Usage

<van-dropdown-menu>
  <van-dropdown-item v-model="value1" :options="option1" />
  <van-dropdown-item v-model="value2" :options="option2" />
</van-dropdown-menu>

import { ref } from 'vue';

export default {
  setup() {
    const value1 = ref(0);
    const value2 = ref('a');
    const option1 = [
      { text: 'Option1', value: 0 },
      { text: 'Option2', value: 1 },
      { text: 'Option3', value: 2 },
    ];
    const option2 = [
      { text: 'Option A', value: 'a' },
      { text: 'Option B', value: 'b' },
      { text: 'Option C', value: 'c' },
    ];

    return {
      value1,
      value2,
      option1,
      option2,
    };
  },
};

Custom Content

<van-dropdown-menu>
  <van-dropdown-item v-model="value" :options="options" />
  <van-dropdown-item title="Title" ref="item">
    <van-cell center title="Title">
      <template #right-icon>
        <van-switch v-model="switch1" size="24" />
      </template>
    </van-cell>
    <van-cell center title="Title">
      <template #right-icon>
        <van-switch v-model="switch2" size="24" />
      </template>
    </van-cell>
    <div style="padding: 5px 16px;">
      <van-button type="primary" block round @click="onConfirm">
        Confirm
      </van-button>
    </div>
  </van-dropdown-item>
</van-dropdown-menu>

import { ref } from 'vue';

export default {
  setup() {
    const item = ref(null);
    const value = ref(0);
    const switch1 = ref(false);
    const switch2 = ref(false);
    const options = [
      { text: 'Option1', value: 0 },
      { text: 'Option2', value: 1 },
      { text: 'Option3', value: 2 },
    ];
    const onConfirm = () => {
      item.value.toggle();
    };

    return {
      item,
      value,
      switch1,
      switch2,
      options,
      onConfirm,
    };
  },
};

Custom Active Color

Use active-color prop to custom active color of the title and options.

<van-dropdown-menu active-color="#ee0a24">
  <van-dropdown-item v-model="value1" :options="option1" />
  <van-dropdown-item v-model="value2" :options="option2" />
</van-dropdown-menu>

Expand Direction

<van-dropdown-menu direction="up">
  <van-dropdown-item v-model="value1" :options="option1" />
  <van-dropdown-item v-model="value2" :options="option2" />
</van-dropdown-menu>

Disabled

<van-dropdown-menu>
  <van-dropdown-item v-model="value1" disabled :options="option1" />
  <van-dropdown-item v-model="value2" disabled :options="option2" />
</van-dropdown-menu>

API

DropdownMenu Props

Attribute	Description	Type	Default
active-color	Active color of title and option	string	#1989fa
direction	Expand direction, can be set to up	string	down
z-index	z-index of menu item	number | string	10
duration	Transition duration, unit second	number | string	0.2
overlay	Whether to show overlay	boolean	true
close-on-click-overlay	Whether to close when overlay is clicked	boolean	true
close-on-click-outside	Whether to close when outside is clicked	boolean	true

DropdownItem Props

Attribute	Description	Type	Default
v-model	Value of current option	number | string	-
title	Item title	string	Text of selected option
options	Options	Option[]	[]
disabled	Whether to disable dropdown item	boolean	false
lazy-render	Whether to lazy render util opened	boolean	true
title-class	Title class	string | Array | object	-
teleport	Specifies a target element where DropdownItem will be mounted	string | Element	-

DropdownItem Events

Event	Description	Arguments
change	Emitted select option and value changed	value
open	Emitted when opening menu	-
close	Emitted when closing menu	-
opened	Emitted when menu is opened	-
closed	Emitted when menu is closed	-

DropdownItem Slots

Name	Description
default	Content
title	Custom title

DropdownItem Methods

Use ref to get DropdownItem instance and call instance methods.

Name	Description	Attribute	Return value
toggle	Toggle display	show?: boolean	-

Types

The component exports the following type definitions:

import type {
  DropdownMenuProps,
  DropdownItemProps,
  DropdownItemOption,
  DropdownItemInstance,
  DropdownMenuDirection,
} from 'vant';

DropdownItemInstance is the type of component instance:

import { ref } from 'vue';
import type { DropdownItemInstance } from 'vant';

const dropdownItemRef = ref<DropdownItemInstance>();

dropdownItemRef.value?.toggle();

Data Structure of Option

Key	Description	Type
text	Text	string
value	Value	number | string
icon	Left icon	string

Theming

CSS Variables

The component provides the following CSS variables, which can be used to customize styles. Please refer to ConfigProvider component.

Name	Default Value	Description
--van-dropdown-menu-height	48px	-
--van-dropdown-menu-background	var(--van-background-light)	-
--van-dropdown-menu-shadow	0 2px 12px fade(var(--van-gray-7), 12)	-
--van-dropdown-menu-title-font-size	15px	-
--van-dropdown-menu-title-text-color	var(--van-text-color)	-
--van-dropdown-menu-title-active-text-color	var(--van-primary-color)	-
--van-dropdown-menu-title-disabled-text-color	var(--van-text-color-2)	-
--van-dropdown-menu-title-padding	0 var(--van-padding-xs)	-
--van-dropdown-menu-title-line-height	var(--van-line-height-lg)	-
--van-dropdown-menu-option-active-color	var(--van-primary-color)	-
--van-dropdown-menu-content-max-height	80%	-
--van-dropdown-item-z-index	10	-