vant/src/area

Area

Intro

A three-level linkage selection of provinces and cities, usually used in conjunction with Popup component.

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.

<van-area title="Title" :area-list="areaList" />

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.

Sample data:

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

@vant/area-data

Vant officially provides a default area data, which can be imported through @vant/area-data:

yarn add @vant/area-data

import { areaList } from '@vant/area-data';

export default {
  setup() {
    return { areaList };
  },
};

Initial Value

To have a selected value，simply pass the code of target area to value property.

<van-area title="Title" :area-list="areaList" value="110101" />

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.

<van-area title="Title" :area-list="areaList" :columns-num="2" />

Columns Placeholder

columns-placeholder property is used to config placeholder of columns.

<van-area
  title="Title"
  :area-list="areaList"
  :columns-placeholder="['Choose', 'Choose', 'Choose']"
/>

API

Props

Attribute	Description	Type	Default
value	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
item-height	Option height, supports px vw vh rem unit, default px	number | string	44
columns-num	Level of picker	number | string	3
visible-item-count	Count of visible columns	number | string	6
swipe-duration	Duration of the momentum animation，unit ms	number | string	1000
is-oversea-code	The method to validate oversea code	() => boolean	-

Events

Event	Description	Arguments
confirm	Emitted when the confirm button is clicked	result: ConfirmResult
cancel	Emitted when the cancel button is clicked	-
change	Emitted when current option changed	current values，column index

ConfirmResult

An array that contains selected area objects.

[
  {
    code: '330000',
    name: 'Zhejiang Province',
  },
  {
    code: '330100',
    name: 'Hangzhou',
  },
  {
    code: '330105',
    name: 'Xihu District',
  },
];

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
reset	Reset all options by code	code?: string	-

Types

Get the type definition of the Area instance through AreaInstance.

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

const areaRef = ref<AreaInstance>();

areaRef.value?.reset();