{"id":15901,"library":"vue-area-linkage","title":"Vue Area Linkage Picker","description":"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.","status":"active","version":"5.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/dwqs/vue-area-linkage","tags":["javascript","vuejs2","vue","area","picker","area-picker","area-linkage"],"install":[{"cmd":"npm install vue-area-linkage","lang":"bash","label":"npm"},{"cmd":"yarn add vue-area-linkage","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-area-linkage","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the Vue.js 2 component library.","package":"vue","optional":false},{"reason":"Required since v5.0.0 to provide geographical data to the components. Previously, this data was bundled internally.","package":"area-data","optional":false}],"imports":[{"note":"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.","wrong":"import { VueAreaLinkage } from 'vue-area-linkage';","symbol":"VueAreaLinkage","correct":"import VueAreaLinkage from 'vue-area-linkage';\nVue.use(VueAreaLinkage);"},{"note":"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.","wrong":"import AreaSelect from 'vue-area-linkage/dist/lib/AreaSelect';","symbol":"{ AreaSelect, AreaCascader }","correct":"import { AreaSelect, AreaCascader } from 'vue-area-linkage';"},{"note":"Crucial for styling the components. Must be imported separately since v2 or higher.","symbol":"CSS Styles","correct":"import 'vue-area-linkage/dist/index.css';"},{"note":"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.","symbol":"{ pca, pcaa }","correct":"import { pca, pcaa } from 'area-data';"}],"quickstart":{"code":"import Vue from 'vue';\nimport { pca, pcaa } from 'area-data';\nimport 'vue-area-linkage/dist/index.css';\nimport VueAreaLinkage from 'vue-area-linkage';\n\nVue.use(VueAreaLinkage);\n\nexport default {\n  data() {\n    return {\n      selectedProvinceCity: [],\n      selectedProvinceCityArea: []\n    };\n  },\n  methods: {\n    handleSelectChange(value) {\n      console.log('AreaSelect value changed:', value);\n    },\n    handleCascaderChange(value) {\n      console.log('AreaCascader value changed:', value);\n    }\n  },\n  template: `\n    <div>\n      <h2>Province-City Selection</h2>\n      <area-select v-model=\"selectedProvinceCity\" :data=\"pca\" @change=\"handleSelectChange\"></area-select>\n      <p>Selected: {{ selectedProvinceCity }}</p>\n\n      <h2>Province-City-Area Selection</h2>\n      <area-cascader v-model=\"selectedProvinceCityArea\" :data=\"pcaa\" @change=\"handleCascaderChange\"></area-cascader>\n      <p>Selected: {{ selectedProvinceCityArea }}</p>\n\n      <h2>Advanced AreaSelect (Level 2, All type)</h2>\n      <area-select type='all' :level='2' v-model=\"selectedProvinceCityArea\" :data=\"pcaa\"></area-select>\n      <p>Selected (Advanced): {{ selectedProvinceCityArea }}</p>\n    </div>\n  `\n};","lang":"javascript","description":"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."},"warnings":[{"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';`","message":"Starting 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.","severity":"breaking","affected_versions":">=5.0.0"},{"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.","message":"Version 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.","severity":"breaking","affected_versions":">=4.0.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\"`).","message":"The `isLinkage` property on `area-select` was renamed to `disableLinkage` in v5.1.0.","severity":"breaking","affected_versions":">=5.1.0"},{"fix":"Always include `import 'vue-area-linkage/dist/index.css';` in your main entry file or component that uses `vue-area-linkage`.","message":"The CSS styles are not automatically bundled with the components and must be imported separately to ensure proper rendering.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"Version 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`.","severity":"breaking","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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>`.","cause":"`area-data` not installed or not passed to the component.","error":"TypeError: Cannot read properties of undefined (reading 'pca')"},{"fix":"Globally: `import VueAreaLinkage from 'vue-area-linkage'; Vue.use(VueAreaLinkage);`. Locally: `import { AreaSelect } from 'vue-area-linkage'; components: { AreaSelect }`.","cause":"The component was not properly registered globally or locally.","error":"Component is not registered (e.g., `<AreaSelect>` not recognized)"},{"fix":"Add `import 'vue-area-linkage/dist/index.css';` to your main JavaScript entry file or an appropriate global stylesheet.","cause":"The required CSS file has not been imported.","error":"Styles are missing or components appear unstyled."},{"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.","cause":"`vue-area-linkage` is designed for Vue 2 and is not compatible with Vue 3.","error":"Error: \"[Vue warn]: Failed to mount component: template or render function not defined.\" (or similar related to `vue-area-linkage` in Vue 3)"}],"ecosystem":"npm"}