Area - Vant 4

Area

🗺️ Create intuitive location pickers that make selecting provinces, cities, and districts a delightful experience!

Intro

A three-level linkage selection of provinces and cities, usually used in conjunction with Popup component! 🏙️ The Area component provides a smooth, cascading selection experience for geographical locations, perfect for address forms, delivery areas, and location-based services. Make location selection intuitive and user-friendly!

Install 📦

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

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

Usage 🚀

Basic Usage

To initialize Area component, area-list property is required. Get started with a simple three-level area picker! 🎯

areaList Data Structure 📊

An object contains three properties: province_list, city_list and county_list. Each property is a simple key-value object, key is a 6-bit code of the area of which first two bits stand for the province or state, middle two bits are used as city code and the last two are district code, value is the name of the area. If the code stands for an area that has sub-areas, lower bits of it will be filled with 0. Understanding this structure helps you organize your location data effectively! 🗂️

Sample data:

exportdefault { province_list: { 110000: 'Beijing', 330000: 'Zhejiang Province', }, city_list: { 110100: 'Beijing City', 330100: 'Hangzhou', }, county_list: { 110101: 'Dongcheng District', 110102: 'Xicheng District', // .... }, };

China Area Data 🇨🇳

Vant officially provides a default china area data, which can be imported through @vant/area-data. Get comprehensive Chinese location data out of the box! 📍

# with npm npm i @vant/area-data # with yarn yarn add @vant/area-data # with pnpm pnpm add @vant/area-data # with Bun bun add @vant/area-data

import { areaList } from'@vant/area-data'; exportdefault { setup() { return { areaList }; }, };

Model Value 🎯

Bind the currently selected area code via v-model. Keep track of user selections with reactive data binding! ⚡

import { ref } from'vue'; exportdefault { setup() { const value = ref('330302'); return { value }; }, };

Columns Number 📊

columns-num property is used to config number of columns to be displayed. This component has 3 columns corresponding to a 3 level picker by default. Set columns-num with 2, you'll have a 2 level picker. Customize the depth of your location picker! 🎛️

Columns Placeholder 💬

columns-placeholder property is used to config placeholder of columns. Guide users with helpful placeholder text! ✨

API

Props

Attribute	Description	Type	Default
v-model	the code of selected area	string	-
title	Toolbar title	string	-
confirm-button-text	Text of confirm button	string	Confirm
cancel-button-text	Text of cancel button	string	Cancel
area-list	Area list data	object	-
columns-placeholder	Placeholder of columns	string[]	[]
loading	Whether to show loading prompt	boolean	false
readonly	Whether to be readonly	boolean	false
option-height	Option height, supports px``vw``vh``rem unit, default px	*number	string*
columns-num	Level of picker	*number	string*
visible-option-num	Count of visible columns	*number	string*
swipe-duration	Duration of the momentum animation, unit ms	*number	string*

Events

Event	Description	Arguments
confirm	Emitted when the confirm button is clicked	{ selectedValues, selectedOptions, selectedIndexes }
cancel	Emitted when the cancel button is clicked	{ selectedValues, selectedOptions, selectedIndexes }
change	Emitted when current option is changed	{ selectedValues, selectedOptions, selectedIndexes, columnIndex }

Slots

Name	Description	SlotProps
toolbar 3.1.2	Custom toolbar content	-
title	Custom title	-
confirm 3.1.2	Custom confirm button text	-
cancel 3.1.2	Custom cancel button text	-
columns-top	Custom content above columns	-
columns-bottom	Custom content below columns	-

Methods

Use ref to get Area instance and call instance methods.

Name	Description	Attribute	Return value
confirm	Stop scrolling and emit confirm event	-	-
getSelectedOptions	Get current selected options	-	PickerOption[]

Types

The component exports the following type definitions:

importtype { AreaProps, AreaList, AreaInstance, AreaColumnOption } from'vant';

AreaInstance is the type of component instance:

import { ref } from'vue'; importtype { AreaInstance } from'vant'; const areaRef = ref<AreaInstance>(); areaRef.value?.confirm();

Related Docs 📚

• AddressEdit - Complete address editing form
• AddressList - Address management interface
• Picker - Base picker component
• Popup - Modal popup container
• Field - Form input fields
• Button - Interactive buttons
• ConfigProvider - Global configuration
• Advanced Usage - Advanced implementation techniques