Registry / web-framework / vue-area-linkage

vue-area-linkage

library5.1.0jsnpmunverified

vue-area-linkage is a Vue.js 2 component library providing province, city, and district linkage selection pickers. It offers both `AreaSelect` (dropdowns) and `AreaCascader` (cascading menu) components for geographical area selection within China. The current stable version is 5.1.0, and releases appear to be driven by feature enhancements, bug fixes, and updates to its underlying `area-data` dependency, without a fixed cadence. A key differentiator since v5.0.0 is that it no longer bundles area data internally, requiring users to explicitly pass `area-data` through the `data` prop, which significantly reduces bundle size and allows for more flexible, on-demand data loading. Earlier versions (pre-v4) supported street-level selection, which has since been removed.

web-framework

npm install vue-area-linkage

github ↗package ↗

INSTALL

IMPORT

SIG · VUE-AREA-LINKAGE

vue-area-linkage

web-frameworkjavascriptv5.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

VueAreaLinkage

✓ import VueAreaLinkage from 'vue-area-linkage'; Vue.use(VueAreaLinkage);

✗ import { VueAreaLinkage } from 'vue-area-linkage';

This is the default export for global registration via Vue.use(). Individual components like AreaSelect and AreaCascader are not directly exported this way for global use.

{ AreaSelect, AreaCascader }

✓ import { AreaSelect, AreaCascader } from 'vue-area-linkage';

✗ import AreaSelect from 'vue-area-linkage/dist/lib/AreaSelect';

Used for on-demand component import, often with a babel plugin for tree-shaking. Available since v2.1.2. Remember to also import the CSS.

CSS Styles

✓ import 'vue-area-linkage/dist/index.css';

Crucial for styling the components. Must be imported separately since v2 or higher.

{ pca, pcaa }

✓ import { pca, pcaa } from 'area-data';

These provide province-city-area data. `pca` is province-city, `pcaa` is province-city-area. Required to be passed as a prop to components since v5.0.0.

This quickstart demonstrates how to register and use both `AreaSelect` and `AreaCascader` components with explicitly imported geographical data (`pca` and `pcaa`) as required by v5+ of the library. It shows basic province-city and province-city-area selection, along with a more advanced `AreaSelect` configuration.

import Vue from 'vue'; import { pca, pcaa } from 'area-data'; import 'vue-area-linkage/dist/index.css'; import VueAreaLinkage from 'vue-area-linkage'; Vue.use(VueAreaLinkage); export default { data() { return { selectedProvinceCity: [], selectedProvinceCityArea: [] }; }, methods: { handleSelectChange(value) { console.log('AreaSelect value changed:', value); }, handleCascaderChange(value) { console.log('AreaCascader value changed:', value); } }, template: ` <div> <h2>Province-City Selection</h2> <area-select v-model="selectedProvinceCity" :data="pca" @change="handleSelectChange"></area-select> <p>Selected: {{ selectedProvinceCity }}</p> <h2>Province-City-Area Selection</h2> <area-cascader v-model="selectedProvinceCityArea" :data="pcaa" @change="handleCascaderChange"></area-cascader> <p>Selected: {{ selectedProvinceCityArea }}</p> <h2>Advanced AreaSelect (Level 2, All type)</h2> <area-select type='all' :level='2' v-model="selectedProvinceCityArea" :data="pcaa"></area-select> <p>Selected (Advanced): {{ selectedProvinceCityArea }}</p> </div> ` };

Debug

Known issues

breakingStarting with v5.0.0, the package no longer bundles geographical data. Users must explicitly install `area-data` and pass the data (e.g., `pca` or `pcaa`) to the components via the `:data` prop.

fix

Install `area-data` (`npm i area-data`) and modify your component usage: `<area-select :data="pca"></area-select>`. Also, update your imports: `import { pca, pcaa } from 'area-data';`

affects: >=5.0.0

breakingVersion 4.0.0 removed support for street-level selection, limiting components to province, city, and district levels only. The `level` prop no longer accepts a value of 3.

fix

Review existing usage that might have relied on street-level selection and adjust the `level` prop to 0, 1, or 2 as appropriate. If street data is still required, consider an older version or an alternative library.

affects: >=4.0.0

breakingThe `isLinkage` property on `area-select` was renamed to `disableLinkage` in v5.1.0.

fix

Replace `isLinkage` with `disableLinkage` in your `area-select` component definitions. Note that the logic of the property might also be inverted (e.g., `isLinkage="false"` becomes `disableLinkage="true"`).

affects: >=5.1.0

gotchaThe CSS styles are not automatically bundled with the components and must be imported separately to ensure proper rendering.

fix

Always include `import 'vue-area-linkage/dist/index.css';` in your main entry file or component that uses `vue-area-linkage`.

affects: >=2.0.0

breakingVersion 2.0.0 removed the dependency on `element-ui`, which significantly reduced the bundle size but might require adjustments if your project implicitly relied on `element-ui`'s styles or components being present through `vue-area-linkage`.

fix

Ensure `element-ui` is explicitly installed and configured if your project still needs it. No direct fix needed for `vue-area-linkage` usage itself, but be aware of style changes.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'pca')

`area-data` not installed or not passed to the component.

fix

Install `area-data` (`npm i area-data`) and ensure it's imported and bound to the `:data` prop, e.g., `<area-select :data="pca"></area-select>`.

Component is not registered (e.g., `<AreaSelect>` not recognized)

The component was not properly registered globally or locally.

fix

Globally: `import VueAreaLinkage from 'vue-area-linkage'; Vue.use(VueAreaLinkage);`. Locally: `import { AreaSelect } from 'vue-area-linkage'; components: { AreaSelect }`.

Styles are missing or components appear unstyled.

The required CSS file has not been imported.

fix

Add `import 'vue-area-linkage/dist/index.css';` to your main JavaScript entry file or an appropriate global stylesheet.

Error: "[Vue warn]: Failed to mount component: template or render function not defined." (or similar related to `vue-area-linkage` in Vue 3)

`vue-area-linkage` is designed for Vue 2 and is not compatible with Vue 3.

fix

This library is for Vue 2 applications only. For Vue 3, you will need to find a different area linkage component or migrate your project to Vue 2 if this component is critical.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

vuerequiredPeer dependency for the Vue.js 2 component library.

area-datarequiredRequired since v5.0.0 to provide geographical data to the components. Previously, this data was bundled internally.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dwqs/vue-area-linkage ↗

packagehttps://www.npmjs.com/package/vue-area-linkage ↗