Region

Chinese administrative divisions selector component

Repository status

Detailed changes for each release are documented in Changelog

If you are using vue 2.x version, please use v-region 2.x version instead

Installation

Install v-region component in to your project

npmyarnpnpm

npm i v-region

npm i v-region

yarn add v-region

yarn add v-region

pnpm add v-region

pnpm add v-region

Globally install component

import { createApp } from 'vue'
import App from './app.vue'
import Region from 'v-region'

const app = createApp(App)
/**
 * Globally register region components
 * v-region-group
 * v-region-selects
 * v-region-columns
 * v-region-city-picker
 * v-region-text
 */
app.use(Region)
app.mount('#app')

import { createApp } from 'vue'
import App from './app.vue'
import Region from 'v-region'

const app = createApp(App)
/**
 * Globally register region components
 * v-region-group
 * v-region-selects
 * v-region-columns
 * v-region-city-picker
 * v-region-text
 */
app.use(Region)
app.mount('#app')

Partial use of components is the more recommended way to use them, and it is also more conducive to code splitting during project packaging, to achieve better resource reference on demand

vue

<template>
  <RegionSelects />
</template>

<script setup>
import { RegionSelects } from 'v-region'
</script>

<template>
  <RegionSelects />
</template>

<script setup>
import { RegionSelects } from 'v-region'
</script>

Examples

Select menus mode

html

<RegionSelects :city="false" language="en" />

<RegionSelects :city="false" language="en" />

html

<RegionSelects :area="false" language="en" />

<RegionSelects :area="false" language="en" />

html

<RegionSelects language="en" />

<RegionSelects language="en" />

html

<RegionSelects :town="true" language="en" />

<RegionSelects :town="true" language="en" />

The response data for change event

{}

Selected items value binding

vue

<template>
  <RegionSelects
    :town="true"
    language="en"
    v-model="region"
  />
</template>

<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
const region = ref({
  province: '350000',
  city: '350100',
  area: '350104',
  town: '350104008'
})
</script>

<template>
  <RegionSelects
    :town="true"
    language="en"
    v-model="region"
  />
</template>

<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
const region = ref({
  province: '350000',
  city: '350100',
  area: '350104',
  town: '350104008'
})
</script>

Disabled state

html

<RegionSelects
  :town="true"
  :disabled="true"
  language="en"
  v-model="region"
/>

<RegionSelects
  :town="true"
  :disabled="true"
  language="en"
  v-model="region"
/>

Plain text mode

Administrative area information displayed by plain text

vue

<template>
  <RegionText
    v-model="region"
    language="en"
  />
</template>

<script setup>
import { ref } from 'vue'
import { RegionText } from 'v-region'
const region = ref({
  province: '350000',
  city: '350100',
  area: '350104',
  town: '350104008'
})
</script>

<template>
  <RegionText
    v-model="region"
    language="en"
  />
</template>

<script setup>
import { ref } from 'vue'
import { RegionText } from 'v-region'
const region = ref({
  province: '350000',
  city: '350100',
  area: '350104',
  town: '350104008'
})
</script>

Separator

Apply specified separators between administrative level names at each level to increase the readability of information

html

<RegionText
  v-model="region"
  separator="-"
/>

<RegionText
  v-model="region"
  separator="-"
/>

Group mode

Use grouping to toggle the selection mode for displaying administrative regions

Group selector mode

html

<RegionGroup v-model="region" language="en" />

<RegionGroup v-model="region" language="en" />

Group selector mode using built-in buttons as trigger objects

Group core module

html

<RegionGroupCore language="en" v-model="region" />

<RegionGroupCore language="en" v-model="region" />

Region

No matched items

The core module can be freely matched with other interactive forms

Group mode custom trigger objects

Use scoped slots to custom trigger objects

html

<RegionGroup language="en" :town="true">
  <template #default="{ region, visible }">
    <button
      type="button"
      class="btn btn-success"
    >
      region: <span v-text="resultText(region)" />,
      visible: <span v-text="visible" />
    </button>
  </template>
</RegionGroup>

<RegionGroup language="en" :town="true">
  <template #default="{ region, visible }">
    <button
      type="button"
      class="btn btn-success"
    >
      region: <span v-text="resultText(region)" />,
      visible: <span v-text="visible" />
    </button>
  </template>
</RegionGroup>

Two data fields are output in the scoped slots

region current Region Selection Data Model
visible the dropdown container open state

Columns mode

Selection mode to display administrative regions side by side using multiple data columns

Columns selector mode

html

<RegionColumns language="en" v-model="region" />

<RegionColumns language="en" v-model="region" />

Group selector mode using built-in buttons as trigger objects

Columns core module

html

<RegionColumnsCore language="en" v-model="region" />

<RegionColumnsCore language="en" v-model="region" />

北京市
天津市
河北省
山西省
内蒙古自治区
辽宁省
吉林省
黑龙江省
上海市
江苏省
浙江省
安徽省
福建省
江西省
山东省
河南省
湖北省
湖南省
广东省
广西壮族自治区
海南省
重庆市
四川省
贵州省
云南省
西藏自治区
陕西省
甘肃省
青海省
宁夏回族自治区
新疆维吾尔自治区
香港特别行政区
澳门特别行政区
台湾省

The core module can be freely matched with other interactive forms

Columns mode custom trigger objects

Use scoped slots to custom trigger objects

html

<RegionColumns language="en" :town="true">
  <template #default="{ region, visible }">
    <button
      type="button"
      class="btn btn-success"
    >
      region: <span v-text="resultText(region)" />,
      visible: <span v-text="visible" />
    </button>
  </template>
</RegionColumns>

<RegionColumns language="en" :town="true">
  <template #default="{ region, visible }">
    <button
      type="button"
      class="btn btn-success"
    >
      region: <span v-text="resultText(region)" />,
      visible: <span v-text="visible" />
    </button>
  </template>
</RegionColumns>

Two data fields are output in the scoped slots

region current Region Selection Data Model
visible the dropdown container open state

City Picker mode

vue

<template>
  <RegionCityPicker
    language="en"
    v-model="selected"
    @change="change"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { RegionCityPicker } from 'v-region'
import type { RegionItem } from 'v-region'

const selected = ref<string[]>(['110000', '130200', '140100'])
function change (data: RegionItem[]): void {
  console.log(data)
}
</script>

<template>
  <RegionCityPicker
    language="en"
    v-model="selected"
    @change="change"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { RegionCityPicker } from 'v-region'
import type { RegionItem } from 'v-region'

const selected = ref<string[]>(['110000', '130200', '140100'])
function change (data: RegionItem[]): void {
  console.log(data)
}
</script>

The response data for change event

[ { "key": "110000", "value": "北京市" }, { "key": "130200", "value": "唐山市" }, { "key": "140100", "value": "太原市" } ]

collapsing items

By default, if you select more than 2 city items, they will be stored and displayed in a unified manner, and the number of folded storage will be displayed

After setting overflow to true, the selected item will be fully displayed in the trigger object without collapsing

html

<RegionCityPicker
  language="en"
  v-model="selected"
  :overflow="true"
/>

<RegionCityPicker
  language="en"
  v-model="selected"
  :overflow="true"
/>

Props

v-model/modelValue

type RegionKeys | string[]

interface RegionInputModel {
  province: string
  city: string
  area: string
  town: string
}

interface RegionInputModel {
  province: string
  city: string
  area: string
  town: string
}

Binding value of selection items for administrative divisions at each level

Data format

The selection item binding of the city picker RegionCityPicker is bound through the string[] array format

city

type boolean
default true

Use city level, if this level is turned off, all subordinate administrative levels are unavailable

area

type boolean
default true

Use area level, if this level is turned off, all subordinate administrative levels are unavailable

town

type boolean
default false

Use town level

blank

type boolean
default false

Add Please select option in select menus, available on RegionSelects module

disabled

type boolean
default false

Enabled / Disabled component, available on RegionSelects、RegionGroup and RegionColumns modules

language

type string
default 'cn'

The language used by the component

cn 中文
en English

separator

type string
default ''

Separator between administrative region names, available on RegionText mode

overflow

type boolean
default false

When more cities are selected, more than 2 cities are only displayed by quantity, only available on RegionCityPicker mode

true Display all selected city names
false When more than two cities are selected, only the names of the first two cities will be displayed, and other cities will be collapsed

customTriggerClass

type string
default ''

Add custom class to trigger container, work on dropdown selection mode

customContainerClass

type string
default ''

Add custom class to dropdown container, work on dropdown selection mode

Events

Component response events for various types of operations

change

Respond for level selection change

change: (data: RegionModel) => void

change: (data: RegionModel) => void

interface RegionItem {
  key: string
  value: string
}

interface RegionModel {
  province: RegionItem
  city: RegionItem
  area: RegionItem
  town: RegionItem
}

interface RegionItem {
  key: string
  value: string
}

interface RegionModel {
  province: RegionItem
  city: RegionItem
  area: RegionItem
  town: RegionItem
}

You can also directly use the type definition provided by the component

vue

<template>
  <RegionSelects
    v-model="region"
    @change="change"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
import type { RegionInputModel, RegionModel } from 'v-region'

const region = ref<RegionInputModel>({
  province: '350000',
  city: '350100',
  area: '350104',
  town: '350104008'
})

function change (data: RegionModel): void {
  console.log(data)
}
</script>

<template>
  <RegionSelects
    v-model="region"
    @change="change"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { RegionSelects } from 'v-region'
import type { RegionInputModel, RegionModel } from 'v-region'

const region = ref<RegionInputModel>({
  province: '350000',
  city: '350100',
  area: '350104',
  town: '350104008'
})

function change (data: RegionModel): void {
  console.log(data)
}
</script>

complete

In response to the completion of all valid region selections, only available on RegionGroupCore and RegionColumnsCore modules

complete: () => void

complete: () => void

visible-change

Respond for dropdown layer state change(display / close)

'visible-change': (visible: boolean) => void

'visible-change': (visible: boolean) => void

API

Before using component's API, need to declare a ref attribute for the component, declare a ref variable by ref() to hold the element reference(the name must match template ref value) and use it to call API methods

vue

<template>
  <RegionSelects ref="region" />
</template>

<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'

const region = ref()
// call api
region.value.reset()
</script>

<template>
  <RegionSelects ref="region" />
</template>

<script setup>
import { ref } from 'vue'
import { RegionSelects } from 'v-region'

const region = ref()
// call api
region.value.reset()
</script>

reset

Reset all level data

reset: () => void

reset: () => void

Region ​

Installation ​

Examples ​

Select menus mode ​

Selected items value binding ​

Disabled state ​

Plain text mode ​

Separator ​

Group mode ​

Group selector mode ​

Group core module ​

Group mode custom trigger objects ​

Columns mode ​

Columns selector mode ​

Columns core module ​

Columns mode custom trigger objects ​

City Picker mode ​

collapsing items ​

Props ​

v-model/modelValue ​

city ​

area ​

town ​

blank ​

disabled ​

language ​

separator ​

overflow ​

customTriggerClass ​

customContainerClass ​

Events ​

change ​

complete ​

visible-change ​

API ​

reset ​

Region

Installation

Examples

Select menus mode

Selected items value binding

Disabled state

Plain text mode

Separator

Group mode

Group selector mode

Group core module

Group mode custom trigger objects

Columns mode

Columns selector mode

Columns core module

Columns mode custom trigger objects

City Picker mode

collapsing items

Props

v-model/modelValue

city

area

town

blank

disabled

language

separator

overflow

customTriggerClass

customContainerClass

Events

change

complete

visible-change

API

reset