DropdownMenu - Vant 4

DropdownMenu

📋 Create elegant dropdown menus that make option selection a breeze!

🎯 Intro

Meet the DropdownMenu component - your ultimate solution for space-efficient option selection! 🚀 Perfect for filters, sorting options, or any scenario where you need to present multiple choices without cluttering your interface. With smooth animations, customizable styling, and intuitive interactions, your users will love how easy it is to navigate through options! ✨

📦 Install

Get your DropdownMenu components ready for action! Register both DropdownMenu and DropdownItem globally via app.use and start creating intuitive selection interfaces! 🎯 Check out our Component Registration guide for more installation options.

import { createApp } from'vue'; import { DropdownMenu, DropdownItem } from'vant'; const app = createApp(); app.use(DropdownMenu); app.use(DropdownItem);

🎨 Usage

📋 Basic Usage

The foundation of great user experience! Create simple, clean dropdown menus that let users select from predefined options effortlessly. Perfect for categories, filters, or any selection scenario! 🌟

import { ref } from'vue'; exportdefault { 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

Go beyond simple text options! Create rich, interactive dropdown content with custom components, switches, buttons, or any Vue elements. Perfect for complex filters or advanced selection interfaces! 🛠️

import { ref } from'vue'; exportdefault { setup() { const menuRef = ref(null); const itemRef = 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 }, ]; constonConfirm = () => { item.value.toggle(); // or// menuRef.value.close(); }; return { menuRef, itemRef, value, switch1, switch2, options, onConfirm, }; }, };

🌈 Custom Active Color

Make it match your brand! Use the active-color prop to customize the color of active titles and selected options, ensuring perfect integration with your design system. 🎯

👆 Swipe Items

Handle lots of options gracefully! When you have many dropdown items, enable horizontal swiping by setting the swipe-threshold prop. Your users can easily navigate through all available options! 📱

⬆️ Expand Direction

Control where your dropdown appears! Set the expand direction to up when you need the menu to open upward - perfect for bottom navigation or when space is limited below! 🔄

🚫 Disabled

Sometimes options need to be temporarily unavailable. Easily disable dropdown items to provide visual feedback while maintaining a clean interface structure! 💤

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 | | swipe-threshold | Horizontal scrolling is allowed when the number of items exceeds the threshold and the total width exceeds the width of the menu. | number | string | - | | auto-locate | When the ancestor element is set with a transform, the position of the dropdown menu will be automatically adjusted. | boolean | false |

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
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: number
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

DropdownMenu Methods

Use ref to get DropdownMenu instance and call instance methods.

Name	Description	Attribute	Return value
close	Close all dropdown items	-	-

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:

importtype { DropdownMenuProps, DropdownItemProps, DropdownItemOption, DropdownItemInstance, DropdownMenuInstance, DropdownMenuDirection, } from'vant';

DropdownMenuInstance and DropdownItemInstance are the types of component instances:

import { ref } from'vue'; importtype { DropdownMenuInstance, DropdownItemInstance } from'vant'; const dropdownMenuRef = ref<DropdownMenuInstance>(); const dropdownItemRef = ref<DropdownItemInstance>(); dropdownMenuRef.value?.close(); dropdownItemRef.value?.toggle();

Data Structure of Option

Key	Description	Type
text	Text	string
value	Value	*number
disabled	Whether to disable option	boolean
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-2)	-
--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-option-disabled-color	var(--van-text-color-3)	-
--van-dropdown-menu-content-max-height	80%	-
--van-dropdown-item-z-index	10	-

## 🔗 Related Docs

- [Picker](./picker) - Column-based option selection
- [ActionSheet](./action-sheet) - Bottom action selection
- [Popup](./popup) - Modal overlay components
- [NavBar](./nav-bar) - Navigation bar with dropdown support
- [Tab](./tab) - Tabbed navigation
- [Field](./field) - Form input components
- [Button](./button) - Interactive button components
- [ConfigProvider](./config-provider) - Global configuration
- [Advanced Usage](./advanced-usage) - Advanced component techniques