vue-select Documentation

1. Project Overview & Quickstart (sagalbot/vue-select) Copy Chapter

File: README.md Copy Chapter

vue-select [](https://coveralls.io/github/sagalbot/vue-select?branch=master)

Everything you wish the HTML <select> element could do, wrapped up into a lightweight, zero
dependency, extensible Vue component.

Vue Select is a feature rich select/dropdown/typeahead component. It provides a default
template that fits most use cases for a filterable select dropdown. The component is designed to be as
lightweight as possible, while maintaining high standards for accessibility,
developer experience, and customization.

• Tagging
• Filtering / Searching
• Vuex Support
• AJAX Support
• SSR Support
• Accessible
• ~20kb Total / ~5kb CSS / ~15kb JS
• Select Single/Multiple Options
• Customizable with slots and SCSS variables
• Zero dependencies

Documentation Copy Chapter

Complete documentation and examples available at https://vue-select.org.

• API Documentation
• Vue 2 CodePen Template
• Vue 3 CodePen Template

Sponsors :tada: Copy Chapter

It takes a lot of effort to maintain this project. If it has saved you development time, please consider sponsoring the project
with GitHub sponsors!

Huge thanks to the sponsors and contributors that make Vue Select possible!

Get started Copy Chapter

Vue 3 / Vue Select 4.x-beta

Vue 3 support is on the beta channel: vue-select@beta, and will become the new default when v4 is released. See #1579 for more details!

Install:

yarn add vue-select@beta

# or use npm

npm install vue-select@beta

Then, import and register the component:

# main.ts or main.js

import { createApp } from "vue";
import App from "./App.vue";

import { VueSelect } from "vue-select";

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

The component itself does not include any CSS. You'll need to include it separately in your Component.vue:

<style>
@import "vue-select/dist/vue-select.css";
</style>

Vue 2 / Vue Select 3.x

Install:

yarn add vue-select

# or use npm

npm install vue-select

Then, import and register the component:

import Vue from "vue";
import vSelect from "vue-select";

Vue.component("v-select", vSelect);

The component itself does not include any CSS. You'll need to include it separately:

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

You can also include vue-select directly in the browser. Check out the
documentation for loading from CDN..

License Copy Chapter

MIT

File: docs/api/events.md Copy Chapter

`input` Copy Chapter

Triggered when the selected value changes. Used internally for v-model.

/**
 * @param {Object|String} val - selected option.
 */
this.$emit("input", val);

`open` Copy Chapter

Triggered when the dropdown is open.

this.$emit("open");

`close` Copy Chapter

Triggered when the dropdown is closed.

this.$emit("close");

`option:selecting` Copy Chapter

Triggered after an option has been selected, before updating internal state.

this.$emit("option:selecting", selectedOption);

`option:selected` Copy Chapter

Triggered when an option has been selected, after updating internal state.

this.$emit("option:selected", selectedOption);

`option:deselecting` Copy Chapter

Triggered when an option has been deselected, before updating internal state.

this.$emit("option:deselecting", selectedOption);

`option:deselected` Copy Chapter

Triggered when an option has been deselected, after updating internal state.

this.$emit("option:deselected", deselectedOption);

`option:created` Copy Chapter

Triggered when taggable is true and a new option has been created.

/**
 * @param {Object} newOption - created option
 */
this.$emit("option:created", newOption);

`search` Copy Chapter

Anytime the search string changes, emit the
'search' event. The event is passed with two
parameters: the search string, and a function
that accepts a boolean parameter to toggle the
loading state.

See the AJAX Guide
for a complete example.

/**
 * @param {String} searchString - the search string
 * @param {Function} toggleLoading - function to toggle loading state, accepts true or false boolean
 */
this.$emit('search', this.search, this.toggleLoading);

<v-select
    @search="(search, loading) => { 
      loading(true)
      fetchOptions(search).then(() => loading(false))
    }"
/>

`search:blur` Copy Chapter

Triggered when the text input loses focus. The dropdown will close immediately before this
event is triggered.

this.$emit("search:blur");

`search:focus` Copy Chapter

Triggered when the text input gains focus. The dropdown will open immediately before this
event is triggered.

this.$emit("search:focus");

File: docs/api/props.md Copy Chapter

appendToBody Copy Chapter

Append the dropdown element to the end of the body
and size/position it dynamically. Use it if you have
overflow or z-index issues.

See Dropdown Position for more details.

appendToBody: {
    type: Boolean,
    default: false
},

autocomplete Copy Chapter

The value provided here will be bound to the autocomplete
HTML attribute
on the search input. Defaults to off.

autocomplete: {
    type: String,
    default: 'off'
},

autoscroll Copy Chapter

When true, the dropdown will automatically scroll to ensure
that the option highlighted is fully within the dropdown viewport
when navigating with keyboard arrows.

autoscroll: {
  type: Boolean,
  default: true
}

calculatePosition Copy Chapter

When appendToBody is true, this function is responsible for positioning the drop down list.

If a function is returned from calculatePosition, it will be called when the drop down list
is removed from the DOM. This allows for any garbage collection you may need to do.

See Dropdown Position for more details.

calculatePosition: {
    type: Function,
    /**
     * @param dropdownList {HTMLUListElement}
     * @param component {Vue} current instance of vue select
     * @param width {string} calculated width in pixels of the dropdown menu
     * @param top {string} absolute position top value in pixels relative to the document
     * @param left {string} absolute position left value in pixels relative to the document
     * @return {function|void}
     */
    default(dropdownList, component, {width, top, left}) {
      dropdownList.style.top = top;
      dropdownList.style.left = left;
      dropdownList.style.width = width;
    }
}

clearable Copy Chapter

Can the user clear the selected property?

clearable: {
	type: Boolean,
	default: true
},

clearSearchOnBlur Copy Chapter

Enables/disables clearing the search text when the search input is blurred.

clearSearchOnBlur: {
    type: Function,
    default: function ({ clearSearchOnSelect, multiple }) {
      return clearSearchOnSelect && !multiple
    }
},

clearSearchOnSelect Copy Chapter

Enables/disables clearing the search text when an option is selected.

clearSearchOnSelect: {
	type: Boolean,
	default: true
},

closeOnSelect Copy Chapter

Close a dropdown when an option is chosen. Set to false to keep the dropdown
open (useful when combined with multi-select, for example)

closeOnSelect: {
	type: Boolean,
	default: true
},

components Copy Chapter

API to overwrite default vue-select components with your own. This can be used to change the clear button or select chevron with your own markup.

The object provided to the components prop will be merged with Vue Select's default components.

See Components guide for more details.

import Deselect from './Deselect';
import OpenIndicator from './OpenIndicator';

// ...

components: {
  type: Object,
  default: function () {
      Deselect,
      OpenIndicator
  }
},

createOption Copy Chapter

User defined function for adding Options

createOption: {
  type: Function,
  default(newOption) {
    if (typeof this.optionList[0] === 'object') {
      newOption = {[this.label]: newOption}
    }

    this.$emit('option:created', newOption)
    return newOption
  }
},

deselectFromDropdown Copy Chapter

Determines whether the user can deselect an option by clicking
it from within the dropdown menu.

deselectFromDropdown: {
    type: Boolean,
    default: false
},

dir Copy Chapter

Sets RTL support. Accepts ltr, rtl, auto.

dir: {
	type: String,
	default: "auto"
},

disabled Copy Chapter

Disable the entire component.

disabled: {
	type: Boolean,
	default: false
},

dropdownShouldOpen Copy Chapter

Determines whether the dropdown should open. Used
for overriding the default dropdown behaviour. Receives
the vue-select instance as the single argument to the function.

dropdownShouldOpen: {
    type: Function,
    default({noDrop, open, mutableLoading}) {
      return noDrop ? false : open && !mutableLoading;
    }
}

filter Copy Chapter

Callback to filter results when search text
is provided. Default implementation loops
each option, and returns the result of
this.filterBy.

filter: {
	type: Function,
	default(options, search) {
		return options.filter(option => {
			let label = this.getOptionLabel(option);
			if (typeof label === "number") {
				label = label.toString();
			}
			return this.filterBy(option, label, search);
		});
	}
},

filterable Copy Chapter

When true, existing options will be filtered
by the search text. Should not be used in conjunction
with taggable.

filterable: {
	type: Boolean,
	default: true
},

filterBy Copy Chapter

Callback to determine if the provided option should
match the current search text. Used to determine
if the option should be displayed.

filterBy: {
  type: Function,
  default(option, label, search) {
    return (label || '').toLocaleLowerCase().indexOf(search.toLocaleLowerCase()) > -1
  }
},

getOptionKey Copy Chapter

Callback to get an option key. If option
is an object and has an id, returns option.id
by default, otherwise tries to serialize option
to JSON.

The key must be unique for an option.

getOptionKey: {
  type: Function,
  default(option) {
    if (typeof option === 'object' && option.id) {
      return option.id
    } else {
      try {
        return JSON.stringify(option)
      } catch(e) {
        return console.warn(
          `[vue-select warn]: Could not stringify option ` +
          `to generate unique key. Please provide 'getOptionKey' prop ` +
          `to return a unique key for each option.\n` +
          'https://vue-select.org/api/props.html#getoptionkey'
        )
        return null
      }
    }
  }
},

getOptionLabel Copy Chapter

Callback to generate the label text. If {option}
is an object, returns option[this.label] by default.

Label text is used for filtering comparison and
displaying. If you only need to adjust the
display, you should use the option and
selected-option slots.

getOptionLabel: {
  type: Function,
  default(option) {
    if (typeof option === 'object') {
      if (!option.hasOwnProperty(this.label)) {
        return console.warn(
          `[vue-select warn]: Label key "option.${this.label}" does not` +
          ` exist in options object ${JSON.stringify(option)}.\n` +
          'https://vue-select.org/api/props.html#getoptionlabel'
        )
      }
      return option[this.label]
    }
    return option;
  }
},

inputId Copy Chapter

Sets the id of the input element.

inputId: {
	type: String
},

label Copy Chapter

Tells vue-select what key to use when generating option
labels when each option is an object.

label: {
	type: String,
	default: "label"
},

loading Copy Chapter

Show spinner if the component is in a loading state.

loading: {
	type: Boolean,
	default: false
},

maxHeight Copy Chapter

::: warning Deprecated in v2.x & Removed in v3.0
This prop was removed in v3.0. You can use the $vs-dropdown-max-height
SCSS variable to adjust this setting in v3.x.
:::

Sets the max-height property on the dropdown list.

maxHeight: {
	type: String,
	default: "400px"
},

multiple Copy Chapter

Equivalent to the multiple attribute on a <select> input.

multiple: {
	type: Boolean,
	default: false
},

noDrop Copy Chapter

Disable the dropdown entirely.

noDrop: {
	type: Boolean,
	default: false
},

onTab Copy Chapter

Select the current value if selectOnTab is enabled.

onTab: {
	type: Function,
	default: function() {
		if (this.selectOnTab) {
			this.typeAheadSelect();
		}
	}
},

options Copy Chapter

An array of strings or objects to be used as dropdown choices.
If you are using an array of objects, vue-select will look for
a label key (ex. [{label: 'Canada', value: 'CA'}]). A
custom label key can be set with the label prop.

options: {
	type: Array,
	default() {
		return [];
	}
},

placeholder Copy Chapter

Equivalent to the placeholder attribute on an ``.

placeholder: {
	type: String,
	default: ""
},

pushTags Copy Chapter

When true, newly created tags will be added to
the options list.

pushTags: {
	type: Boolean,
	default: false
},

reduce Copy Chapter

When working with objects, the reduce
prop allows you to transform a given
object to only the information you
want passed to a v-model binding
or @input event.

reduce: {
  type: Function,
  default: option => option,
},

resetOnOptionsChange Copy Chapter

When false, updating the options will not reset the selected value.

Since v3.4+ the prop accepts either a boolean or function that returns a boolean.

If defined as a function, it will receive the params listed below.

/**
* @type {Boolean|Function}
* @param {Array} newOptions
* @param {Array} oldOptions
* @param {Array} selectedValue
*/
resetOnOptionsChange: {
    default: false,
    validator: (value) => ['function', 'boolean'].includes(typeof value)
},

searchable Copy Chapter

Enable/disable filtering the options.

searchable: {
	type: Boolean,
	default: true
},

selectable Copy Chapter

The selectable prop determines if an option is selectable or not. If selectable returns false
for a given option, it will be displayed with a vs__dropdown-option--disabled class. The option
will be disabled and unable to be selected.

selectable: {
  type: Function,
  /**
   * @param {Object|String} option
   * @return {boolean}
   */
  default: option => true,
},

selectOnTab Copy Chapter

When true, hitting the 'tab' key will select the current select value

selectOnTab: {
	type: Boolean,
	default: false
}

tabindex Copy Chapter

Set the tabindex for the input field.

tabindex: {
	type: Number,
	default: null
},

taggable Copy Chapter

Enable/disable creating options from searchInput.

taggable: {
	type: Boolean,
	default: false
},

transition Copy Chapter

Sets a Vue transition property on the .dropdown-menu. vue-select
does not include CSS for transitions, you'll need to add them yourself.

transition: {
	type: String,
	default: "fade"
},

uid Copy Chapter

A unique identifier used to generate IDs and DOM attributes.
Must be unique for every instance of the component.

uid: {
  type: [String, Number],
  default: () => uniqueId(),
},

value Copy Chapter

Contains the currently selected value. Very similar to a
value attribute on an ``. You can listen for changes
using the 'input' event.

value: {
	default: null
},

File: docs/api/slots.md Copy Chapter

::: tip
Vue Select leverages scoped slots to allow for total customization of the presentation layer.
Slots can be used to change the look and feel of the UI, or to simply swap out text.
:::

`footer` Copy Chapter

Displayed at the bottom of the component, below .vs__dropdown-toggle.

When implementing this slot, you'll likely need to use appendToBody to position the dropdown.
Otherwise content in this slot will affect it's positioning.

• search {string} - the current search query
• loading {boolean} - is the component loading
• searching {boolean} - is the component searching
• filteredOptions {array} - options filtered by the search text
• deselect {function} - function to deselect an option

attributes: {
  'ref': 'openIndicator',
  'role': 'presentation',
  'class': 'vs__open-indicator',
}

/**
   * Attributes to be bound to a search input.
   */
  attributes: {
    'disabled': this.disabled,
    'placeholder': this.searchPlaceholder,
    'tabindex': this.tabindex,
    'readonly': !this.searchable,
    'id': this.inputId,
    'aria-autocomplete': 'list',
    'aria-labelledby': `vs${this.uid}__combobox`,
    'aria-controls': `vs${this.uid}__listbox`,
    'aria-activedescendant': this.typeAheadPointer > -1
      ? `vs${this.uid}__option-${this.typeAheadPointer}`
      : '',
    'ref': 'search',
    'type': 'search',
    'autocomplete': this.autocomplete,
    'value': this.search,
  },
  /**
   * Events that this element should handle.
   */
  events: {
    'compositionstart': () => this.isComposing = true,
    'compositionend': () => this.isComposing = false,
    'keydown': this.onSearchKeyDown,
    'blur': this.onSearchBlur,
    'focus': this.onSearchFocus,
    'input': (e) => this.search = e.target.value,
  }

<v-select @search="fetchOptions" />

/**
 * Triggered when the search text changes.
 *
 * @param search  {String}    Current search text
 * @param loading {Function}	Toggle loading class
 */
fetchOptions (search, loading) {
  //  ... do some asynchronous stuff!  
},

/**
 * When true, existing options will be filtered
 * by the search text. Should not be used in
 * conjunction with taggable.
 * 
 * @type {Boolean}
 */
filterable: {
	type: Boolean,
	default: true
},

Loading...

<v-select :components="{Deselect}" />

export default {
  data: () => ({
    Deselect: {
      render: createElement => createElement('span', '❌'),
    },
  }),
};

<v-select :components="{OpenIndicator}" />

export default {
  data: () => ({
    selected: ['Canada'],
    OpenIndicator: {
      render: createElement => createElement('span', {class: {'toggle': true}}),
    },
  }),
};

import Vue from 'vue';
import vSelect from 'vue-select';

// Set the components prop default to return our fresh components 
vSelect.props.components.default = () => ({
  Deselect: {
    render: createElement => createElement('span', '❌'),
  },
  OpenIndicator: {
    render: createElement => createElement('span', '🔽'),
  },
});

// Register the component
Vue.component(vSelect)

import {createApp, h} from 'vue';
import vSelect from 'vue-select';

// Set the components prop default to return our fresh components 
vSelect.props.components.default = () => ({
  Deselect: {
    render: () => h('span', '❌'),
  },
  OpenIndicator: {
    render: () => h('span', '🔽'),
  },
});

// Register the component
const app = createApp(App);
app.component('vSelect', vSelect);

<v-select transition="" />

.vs__fade-enter-active,
.vs__fade-leave-active {
    transition: none;
}