Cascader - Vant 4

Cascader

🌳 Navigate through hierarchical data with ease - perfect for location selection, category browsing, and multi-level choices!

Intro 📍

Master multi-level selections! The Cascader component provides an intuitive way to navigate through hierarchical data like provinces/cities, categories, or any nested structure. Perfect for location pickers and complex data navigation! 🗺️✨

Install 📦

Get started with hierarchical selections! Register the Cascader component and unlock powerful multi-level data navigation! 🚀

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

Usage 🎯

Basic Usage 🌟

Create your first cascading selector! Perfect for location selection - from provinces to cities in just a few taps! 🏙️

import { ref } from'vue'; exportdefault { setup() { const show = ref(false); const fieldValue = ref(''); const cascaderValue = ref(''); const options = [ { text: 'Zhejiang', value: '330000', children: [{ text: 'Hangzhou', value: '330100' }], }, { text: 'Jiangsu', value: '320000', children: [{ text: 'Nanjing', value: '320100' }], }, ]; constonFinish = ({ selectedOptions }) => { show.value = false; fieldValue.value = selectedOptions.map((option) => option.text).join('/'); }; return { show, options, onFinish, fieldValue, cascaderValue, }; }, };

Custom Color 🎨

Make it match your brand! Customize the active color to create a cohesive visual experience! 💫

Async Options ⚡

Load data on demand! Perfect for large datasets - fetch child options dynamically as users navigate through levels! 🔄

import { ref } from'vue'; import { closeToast, showLoadingToast } from'vant'; exportdefault { setup() { const show = ref(false); const fieldValue = ref(''); const cascaderValue = ref(''); const options = ref([ { text: 'Zhejiang', value: '330000', children: [], }, ]); constonChange = ({ value }) => { if ( value === options.value[0].value && options.value[0].children.length === 0 ) { showLoadingToast('Loading...'); // mock data requestsetTimeout(() => { options.value[0].children = [ { text: 'Hangzhou', value: '330100' }, { text: 'Ningbo', value: '330200' }, ]; closeToast(); }, 1000); } }; constonFinish = ({ selectedOptions }) => { show.value = false; fieldValue.value = selectedOptions.map((option) => option.text).join('/'); }; return { show, options, onFinish, fieldValue, cascaderValue, }; }, };

Custom Field Names 🏷️

Adapt to your data structure! Use custom field names to work with any data format - no need to transform your existing data! 🔧

import { ref } from'vue'; exportdefault { setup() { const code = ref(''); const fieldNames = { text: 'name', value: 'code', children: 'items', }; const options = [ { name: 'Zhejiang', code: '330000', items: [{ name: 'Hangzhou', code: '330100' }], }, { name: 'Jiangsu', code: '320000', items: [{ name: 'Nanjing', code: '320100' }], }, ]; return { code, options, fieldNames, }; }, };

Custom Content ✨

Make each option unique! Use slots to add icons, badges, or any custom content to your cascader options! 🎭

import { ref } from'vue'; exportdefault { setup() { const code = ref(''); const options = [ { name: 'Zhejiang', code: '330000', items: [{ name: 'Hangzhou', code: '330100' }], }, { name: 'Jiangsu', code: '320000', items: [{ name: 'Nanjing', code: '320100' }], }, ]; return { code, options, }; }, };

API

Props

Attribute	Description	Type	Default
v-model	Value of selected option	*string	number*
title	Title	string	-
options	Options	CascaderOption[]	[]
placeholder	Placeholder of unselected tab	string	Select
active-color	Active color	string	#1989fa

| swipeable | Whether to enable gestures to slide left and right | boolean | true | | closeable | Whether to show close icon | boolean | true | | show-header | Whether to show header | boolean | true | | close-icon | Close icon name | string | cross | | field-names | Custom the fields of options | CascaderFieldNames | { text: 'text', value: 'value', children: 'children' } |

Data Structure of CascaderOption

Key	Description	Type
text	Option text	string
value	Option value	*string
color	Text color	string
children	Cascade children	CascaderOption[]
disabled	Whether to disable option	boolean
className	className for the option	*string

Events

Event	Description	Arguments
change	Emitted when active option changed	*{ value: string
finish	Emitted when all options is selected	*{ value: string
close	Emitted when the close icon is clicked	-
click-tab	Emitted when a tab is clicked	activeTab: number, title: string

Slots

Name	Description	SlotProps
title	Custom title	-
option	Custom option text	{ option: CascaderOption, selected: boolean }
options-top	Custom the content above the options	{ tabIndex: number }
options-bottom	Custom the content below the options	{ tabIndex: number }

Types

The component exports the following type definitions:

importtype { CascaderProps, CascaderOption, CascaderFieldNames } from'vant';

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-cascader-header-height	48px	-
--van-cascader-header-padding	0 var(--van-padding-md)	-
--van-cascader-title-font-size	var(--van-font-size-lg)	-
--van-cascader-title-line-height	20px	-
--van-cascader-close-icon-size	22px	-
--van-cascader-close-icon-color	var(--van-gray-5)	-
--van-cascader-selected-icon-size	18px	-
--van-cascader-tabs-height	48px	-
--van-cascader-active-color	var(--van-danger-color)	-
--van-cascader-options-height	384px	-
--van-cascader-tab-color	var(--van-text-color)	-
--van-cascader-unselected-tab-color	var(--van-text-color-2)	-

## Related Docs 📚

- [Picker](./picker) - Single-level selection component
- [Area](./area) - Specialized area/region picker
- [Field](./field) - Input field integration
- [Popup](./popup) - Cascader popup container
- [Tab](./tab) - Tab navigation component
- [Loading](./loading) - Loading states for async data
- [Toast](./toast) - Show loading and success messages
- [ConfigProvider](./config-provider) - Global configuration
- [Advanced Usage](./advanced-usage) - Component registration guide