vue-select

library3.20.4jsnpmunverified

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.

web-framework

npm install vue-select

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · VUE-SELECT

vue-select

web-frameworkjavascriptv3.20.4

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.

vSelect (Vue 2)

✓ import vSelect from 'vue-select'

✗ 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)

✓ import { VueSelect } from 'vue-select'

✗ 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

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

✗ require('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.

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>

Debug

Known issues

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

affects: >=3.0.0

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

affects: >=4.0.0-beta

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

affects: >=3.0.0

deprecatedWhile 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')`.

affects: >=3.0.0

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

affects: 4.0.0-beta.x

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

3.20.4latest on npm

Audit

Dependencies

vuerequiredPeer dependency for the Vue component. v3.x requires Vue 2.x, v4.x requires Vue 3.x.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sagalbot/vue-select ↗

packagehttps://www.npmjs.com/package/vue-select ↗

homepagehttps://vue-select.org ↗