{"id":12533,"library":"vue-multiselect","title":"Vue Multiselect Component","description":"Vue Multiselect is a versatile, dependency-free multiselect and tagging component designed for Vue 3 applications. Currently at version 3.5.0, it offers a wide range of features including single and multiple selection, tagging capabilities, filtering, search with suggestions, and asynchronous option loading. The library maintains a steady release cadence with frequent bug fixes and minor feature enhancements, as seen in its recent 3.x releases. A key differentiator is its minimal footprint and explicit lack of external runtime dependencies, making it a lightweight choice. It supports Vue's `v-model`, Vuex integration, and fully configurable props for extensive customization. The component ships with TypeScript types, ensuring a robust developer experience for TypeScript users.","status":"active","version":"3.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/shentao/vue-multiselect","tags":["javascript","typescript"],"install":[{"cmd":"npm install vue-multiselect","lang":"bash","label":"npm"},{"cmd":"yarn add vue-multiselect","lang":"bash","label":"yarn"},{"cmd":"pnpm add vue-multiselect","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"VueMultiselect is the default export of the package. It's a Vue component.","wrong":"import { VueMultiselect } from 'vue-multiselect'","symbol":"VueMultiselect","correct":"import VueMultiselect from 'vue-multiselect'"},{"note":"The main CSS file is required for styling. The minified version is also available at `vue-multiselect/dist/vue-multiselect.min.css` but the unminified is generally preferred for development.","wrong":"import 'vue-multiselect/dist/vue-multiselect.min.css'","symbol":"CSS Styles","correct":"import 'vue-multiselect/dist/vue-multiselect.css'"},{"note":"For TypeScript users, various types like `MultiselectOption` can be imported for enhanced type safety when defining options or values.","symbol":"Type (MultiselectOption)","correct":"import type { MultiselectOption } from 'vue-multiselect'"}],"quickstart":{"code":"<template>\n  <div>\n    <VueMultiselect\n      v-model=\"selectedItem\"\n      :options=\"availableOptions\"\n      :multiple=\"true\"\n      :taggable=\"true\"\n      @tag=\"addOptionTag\"\n      tag-placeholder=\"Add as new tag\"\n      placeholder=\"Type to search or add tag\"\n      label=\"name\"\n      track-by=\"code\">\n    </VueMultiselect>\n    <p>Selected: {{ selectedItem }}</p>\n  </div>\n</template>\n\n<script lang=\"ts\">\nimport { defineComponent, ref } from 'vue';\nimport VueMultiselect from 'vue-multiselect';\nimport 'vue-multiselect/dist/vue-multiselect.css';\n\ninterface Option {\n  name: string;\n  code: string;\n}\n\nexport default defineComponent({\n  components: { VueMultiselect },\n  setup() {\n    const selectedItem = ref<Option[]>([\n      { name: 'Apple', code: 'AP' }\n    ]);\n    const availableOptions = ref<Option[]>([\n      { name: 'Apple', code: 'AP' },\n      { name: 'Banana', code: 'BN' },\n      { name: 'Cherry', code: 'CH' }\n    ]);\n\n    const addOptionTag = (newTag: string) => {\n      const tag: Option = {\n        name: newTag,\n        code: newTag.substring(0, 2).toUpperCase() + Math.floor(Math.random() * 10000000)\n      };\n      availableOptions.value.push(tag);\n      selectedItem.value.push(tag);\n    };\n\n    return {\n      selectedItem,\n      availableOptions,\n      addOptionTag\n    };\n  }\n});\n</script>\n\n<style>\n/* Optional: Adjust global styles if needed */\n</style>","lang":"typescript","description":"This example demonstrates how to set up Vue Multiselect with multiple selection, tagging, and options managed using Vue 3's Composition API."},"warnings":[{"fix":"Review and update your CSS selectors for the dropdown to account for its new position, typically as a direct child of `body`. For more control, set the `teleport` prop to `false` in v3.3.1+ to revert to pre-v3.3.0 behavior, or use the `teleportTarget` prop to specify a custom target.","message":"In v3.3.0, the open multiselect dropdown's DOM element began being 'teleported' to the end of the `body`. This change might break existing CSS styling that relies on the dropdown's original position within the DOM tree.","severity":"breaking","affected_versions":">=3.3.0 <3.3.1"},{"fix":"If experiencing issues with Vite, ensure your `@vitejs/plugin-vue` version is compatible and does not inadvertently disable the Options API. Refer to the `vue-multiselect` documentation or `@vitejs/plugin-vue` changelog for known incompatibilities and recommended versions. You might need to downgrade `@vitejs/plugin-vue`.","message":"Vue Multiselect requires Vue's Options API to function correctly. Some versions of `@vitejs/plugin-vue` (specifically v5.2.2 and later) are known to potentially disable the Options API, leading to runtime issues.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Carefully review the migration guide from Vue 2 to Vue 3 for your application, and consult the `vue-multiselect` v3 pre-release notes for any specific `vue-multiselect` related adjustments.","message":"Version 3.0.0 introduced full compatibility with Vue 3. While efforts were made to maintain backward compatibility with v2.x logic, direct upgrades from v2.x may require minor tweaks due to underlying Vue 3 specific changes.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"If previous CSS broke in v3.3.0, setting the `teleport` prop to `false` (which is the default in v3.3.1+) or targeting a specific `teleportTarget` prop can restore expected behavior and styling.","message":"The `teleport` feature introduced in v3.3.0, which moved the dropdown to the end of the `body`, was made optional via a prop in v3.3.1. If you upgraded to v3.3.0 and experienced broken styling, later reverting to v3.3.1+ might require explicit `teleport` prop configuration.","severity":"gotcha","affected_versions":">=3.3.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"This was addressed in v2.1.8 and subsequently in v3.0.0-beta.3 and later stable v3 releases. Ensure you are on a recent stable version of `vue-multiselect` (v3.0.0 or higher) to avoid this issue.","cause":"This error, often `null.blur()`, indicates an attempt to call the `blur` method on a null or undefined element, typically in specific interaction scenarios.","error":"Cannot read properties of null (reading 'blur')"},{"fix":"Update your CSS to target the multiselect dropdown element correctly, considering it might now be a direct child of `body`. Alternatively, set the `teleport` prop to `false` (available since v3.3.1) or specify a custom `teleportTarget` to keep the dropdown within the component's original DOM structure.","cause":"This is likely due to the dropdown's DOM element being 'teleported' to the end of the `body` starting from v3.3.0, changing its position relative to other elements and affecting CSS selectors.","error":"CSS styles for multiselect dropdown are incorrect or not applying as expected after update."}],"ecosystem":"npm"}