Vue Select Component

Common errors

• [Vue warn]: Unknown custom element: <v-select> - did you register the component correctly?

  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.
  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.

• The v-select component appears unstyled or broken, showing default HTML elements.

  cause The required CSS file for `vue-select` has not been imported into your project.
  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.

• TypeError: Cannot read properties of undefined (reading 'install') during Vue.use() or similar.

  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.
  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.

Warnings

• breaking 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.
  Fix: For Vue 2 projects, use `npm install vue-select`. For Vue 3 projects, use `npm install vue-select@beta`.
• breaking 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'`).
  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.
• gotcha Vue Select does not include its CSS by default. You must explicitly import the stylesheet for the component to render correctly and be styled.
  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.
• deprecated 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.
  Fix: Prefer `import vSelect from 'vue-select'` (Vue 2) or `import { VueSelect } from 'vue-select'` (Vue 3) over `const vSelect = require('vue-select')`.
• gotcha 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.
  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.

Install

• npm install vue-select npm
• yarn add vue-select yarn
• pnpm add vue-select pnpm

Imports

• vSelect (Vue 2)
  wrong:

  import { vSelect } from 'vue-select'

  correct:

  import vSelect from 'vue-select'

  For Vue 2 applications using vue-select v3.x, the component is exported as a default export.
• VueSelect (Vue 3)
  wrong:

  import VueSelect from 'vue-select'

  correct:

  import { VueSelect } from 'vue-select'

  For Vue 3 applications using vue-select v4.x-beta, the component is exported as a named export. Ensure you install `vue-select@beta`.
• CSS Styles
  wrong:

  require('vue-select/dist/vue-select.css')

  correct:

  import 'vue-select/dist/vue-select.css';

  The component's CSS must be imported separately. This path is consistent across both v3.x and v4.x.

Quickstart

Demonstrates how to install `vue-select@beta` (for Vue 3), import, globally register the component, and include its essential CSS for basic usage.

import { createApp } from 'vue';
import App from './App.vue';
import { VueSelect } from 'vue-select';
import 'vue-select/dist/vue-select.css';

createApp(App)
  .component('v-select', VueSelect)
  .mount('#app');

// In App.vue template:
// <template>
//   <div id="app">
//     <v-select :options="['Canada', 'United States', 'Mexico']"></v-select>
//   </div>
// </template>