Vue Multiselect Component

Common errors

• Cannot read properties of null (reading 'blur')

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

• CSS styles for multiselect dropdown are incorrect or not applying as expected after update.

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

Warnings

• breaking 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.
  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.
• gotcha 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.
  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`.
• breaking 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.
  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.
• gotcha 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.
  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.

Install

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

Imports

• VueMultiselect
  wrong:

  import { VueMultiselect } from 'vue-multiselect'

  correct:

  import VueMultiselect from 'vue-multiselect'

  VueMultiselect is the default export of the package. It's a Vue component.
• CSS Styles
  wrong:

  import 'vue-multiselect/dist/vue-multiselect.min.css'

  correct:

  import 'vue-multiselect/dist/vue-multiselect.css'

  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.
• Type (MultiselectOption)

  import type { MultiselectOption } from 'vue-multiselect'

  For TypeScript users, various types like `MultiselectOption` can be imported for enhanced type safety when defining options or values.

Quickstart

This example demonstrates how to set up Vue Multiselect with multiple selection, tagging, and options managed using Vue 3's Composition API.

<template>
  <div>
    <VueMultiselect
      v-model="selectedItem"
      :options="availableOptions"
      :multiple="true"
      :taggable="true"
      @tag="addOptionTag"
      tag-placeholder="Add as new tag"
      placeholder="Type to search or add tag"
      label="name"
      track-by="code">
    </VueMultiselect>
    <p>Selected: {{ selectedItem }}</p>
  </div>
</template>

<script lang="ts">
import { defineComponent, ref } from 'vue';
import VueMultiselect from 'vue-multiselect';
import 'vue-multiselect/dist/vue-multiselect.css';

interface Option {
  name: string;
  code: string;
}

export default defineComponent({
  components: { VueMultiselect },
  setup() {
    const selectedItem = ref<Option[]>([
      { name: 'Apple', code: 'AP' }
    ]);
    const availableOptions = ref<Option[]>([
      { name: 'Apple', code: 'AP' },
      { name: 'Banana', code: 'BN' },
      { name: 'Cherry', code: 'CH' }
    ]);

    const addOptionTag = (newTag: string) => {
      const tag: Option = {
        name: newTag,
        code: newTag.substring(0, 2).toUpperCase() + Math.floor(Math.random() * 10000000)
      };
      availableOptions.value.push(tag);
      selectedItem.value.push(tag);
    };

    return {
      selectedItem,
      availableOptions,
      addOptionTag
    };
  }
});
</script>

<style>
/* Optional: Adjust global styles if needed */
</style>