{"id":12571,"library":"vue-select","title":"Vue Select Component","description":"Vue Select is a lightweight, extensible Vue component designed to replace the native HTML `<select>` element, offering enhanced features like filtering, tagging, and AJAX support. The project currently maintains two major lines: the stable version 3.x (latest 3.20.4), which exclusively supports Vue 2, and the actively developed beta channel 4.x (currently 4.0.0-beta.6), which targets Vue 3. While version 3.x receives maintenance updates for critical bug fixes, the primary development effort is focused on the Vue 3 compatible 4.x branch. It differentiates itself by being dependency-free at runtime (aside from Vue itself), highly customizable via slots and SCSS variables, and built with strong emphasis on accessibility. Releases for v3.x have become less frequent as v4.x development progresses towards a stable release, which will likely become the new default for Vue 3 projects.","status":"active","version":"3.20.4","language":"javascript","source_language":"en","source_url":"https://github.com/sagalbot/vue-select","tags":["javascript"],"install":[{"cmd":"npm install vue-select","lang":"bash","label":"npm"},{"cmd":"yarn add vue-select","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-select","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for the Vue component. v3.x requires Vue 2.x, v4.x requires Vue 3.x.","package":"vue","optional":false}],"imports":[{"note":"For Vue 2 applications using vue-select v3.x, the component is exported as a default export.","wrong":"import { vSelect } from 'vue-select'","symbol":"vSelect (Vue 2)","correct":"import vSelect from 'vue-select'"},{"note":"For Vue 3 applications using vue-select v4.x-beta, the component is exported as a named export. Ensure you install `vue-select@beta`.","wrong":"import VueSelect from 'vue-select'","symbol":"VueSelect (Vue 3)","correct":"import { VueSelect } from 'vue-select'"},{"note":"The component's CSS must be imported separately. This path is consistent across both v3.x and v4.x.","wrong":"require('vue-select/dist/vue-select.css')","symbol":"CSS Styles","correct":"import 'vue-select/dist/vue-select.css';"}],"quickstart":{"code":"import { createApp } from 'vue';\nimport App from './App.vue';\nimport { VueSelect } from 'vue-select';\nimport 'vue-select/dist/vue-select.css';\n\ncreateApp(App)\n  .component('v-select', VueSelect)\n  .mount('#app');\n\n// In App.vue template:\n// <template>\n//   <div id=\"app\">\n//     <v-select :options=\"['Canada', 'United States', 'Mexico']\"></v-select>\n//   </div>\n// </template>\n","lang":"typescript","description":"Demonstrates how to install `vue-select@beta` (for Vue 3), import, globally register the component, and include its essential CSS for basic usage."},"warnings":[{"fix":"For Vue 2 projects, use `npm install vue-select`. For Vue 3 projects, use `npm install vue-select@beta`.","message":"Vue Select has separate major versions for Vue 2 (v3.x) and Vue 3 (v4.x). Installing `vue-select` defaults to v3.x (Vue 2), while `vue-select@beta` installs v4.x (Vue 3). Ensure you install the correct version for your Vue project.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Adjust your import statement based on your Vue version and installed `vue-select` version. Use `vSelect` for Vue 2/v3.x and `VueSelect` for Vue 3/v4.x.","message":"The component's default export/named export changed between v3.x and v4.x. v3.x uses a default export (`import vSelect from 'vue-select'`), while v4.x uses a named export (`import { VueSelect } from 'vue-select'`).","severity":"breaking","affected_versions":">=4.0.0-beta"},{"fix":"Add `import 'vue-select/dist/vue-select.css';` to your main JavaScript/TypeScript entry file or a global CSS file, or use `@import 'vue-select/dist/vue-select.css';` in your Vue component's style block.","message":"Vue Select does not include its CSS by default. You must explicitly import the stylesheet for the component to render correctly and be styled.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Prefer `import vSelect from 'vue-select'` (Vue 2) or `import { VueSelect } from 'vue-select'` (Vue 3) over `const vSelect = require('vue-select')`.","message":"While CommonJS `require()` might still work in some environments, it is generally recommended to use ES Module `import` syntax for modern Vue applications, especially when dealing with Vue 3 projects.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Monitor the official GitHub repository and documentation for updates regarding the stable release of v4.0.0. Consider locking the beta version to a specific patch for stability.","message":"The v4.x version for Vue 3 is currently in beta. While generally stable, it might contain minor bugs or experience breaking changes before its stable release. Use with caution in production environments.","severity":"gotcha","affected_versions":"4.0.0-beta.x"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you have correctly registered the component globally (e.g., `Vue.component('v-select', vSelect)` for Vue 2 or `app.component('v-select', VueSelect)` for Vue 3) or declared it in the `components` option of your Vue component.","cause":"The `v-select` component was not globally registered or locally imported/declared in the component where it's being used, or an incorrect import/register method was used for the respective Vue/vue-select version.","error":"[Vue warn]: Unknown custom element: <v-select> - did you register the component correctly?"},{"fix":"Add `import 'vue-select/dist/vue-select.css';` to your main JavaScript/TypeScript entry file, or use `@import 'vue-select/dist/vue-select.css';` in a global stylesheet or component style block.","cause":"The required CSS file for `vue-select` has not been imported into your project.","error":"The v-select component appears unstyled or broken, showing default HTML elements."},{"fix":"Do not use `Vue.use()` with `vue-select`. Instead, register it directly as a component: `Vue.component('v-select', vSelect)` for Vue 2, or `app.component('v-select', VueSelect)` for Vue 3.","cause":"Attempting to install `vue-select` as a Vue plugin (e.g., `Vue.use(vSelect)`), which it is not. `vue-select` is a component, not a plugin with an `install` method.","error":"TypeError: Cannot read properties of undefined (reading 'install') during Vue.use() or similar."}],"ecosystem":"npm"}