vue-select/docs/guide/values.md

Getting and Setting

v-model

The most common use case for vue-select is to have the chosen value synced with a parent component. vue-select takes advantage of the v-model syntax to sync values with a parent. The v-model syntax works with primitives and objects.

<v-select v-model="selected" />

Note that when using the multiple prop, the v-model value will always be an array.

Props and Events

Sometimes v-model might not fit your use case. For example, when working with Vuex, you'll need to trigger a mutation rather than mutating a value directly. In that case, maybe you need to bind a pre-selected value, and trigger a mutation when it changes.

vue-select exposes the value prop and an input event to enable this. This combo of props and events is also how Vue wires up the v-model syntax internally.

Prop: value

The value prop lets vue-select know what value is currently selected. It will accept strings, numbers or objects. If you're using a multiple v-select, you'll want to pass an array.

<v-select :value="selected" />

::: tip 🤓 Anytime you bind the value prop directly, you're responsible for updating the bound variable in your code using the @input event. :::

Event: input

The input event is triggered anytime the value state changes, and is emitted with the value state as it's only parameter.

Vuex Support

The value prop and emit event are very useful when using a state management tool, like Vuex. You can bind the selected value with :value="$store.myValue", and use the input event to trigger a mutation, or dispatch an action – or anything else you might need to do when the selection changes.

<v-select :value="$store.myValue" @input="setSelected" />

methods: {
  setSelected(value) {
     //  trigger a mutation, or dispatch an action  
  }
}

Transforming Selections

When the options array contains objects, vue-select returns the whole object as dropdown value upon selection. This approach makes no assumptions about the data you need, and provides a lot of flexibility. However, there will be situations where maybe you just need to return a single key from an object.

Returning a single key with reduce

If you need to return a single key, or transform the selection before it is synced, vue-select provides a reduce callback that allows you to transform a selected option before it is passed to the @input event. Consider this data structure:

let options = [{code: 'CA', country: 'Canada'}];

If we want to display the country, but return the code to v-model, we can use the reduce prop to receive only the data that's required.

<v-select :options="options" :reduce="country => country.code" label="country" />

Deep Nested Values

The reduce property also works well when you have a deeply nested value:

{
  country: 'canada',
  meta: {
    code: 'ca'
    provinces: [...],
  }
}

<v-select :options="options" :reduce="country => country.meta.code" label="country" />

Single/Multiple Selection

By default, vue-select supports choosing a single value. If you need multiple values, use the multiple boolean prop, much the same way you would on an HTML <select> element. When multiple is true, v-model and value must be an array.

<v-select multiple v-model="selected" :options="['Canada','United States']" />

Tagging

To allow input that's not present within the options, set the taggable prop to true.

<v-select taggable multiple />

If you want added tags to be pushed to the options array, set push-tags to true.

<v-select taggable multiple />

Using taggable & reduce together

When combining taggable with reduce, you must define the createOption prop. The createOption function is responsible for defining the structure of the objects that Vue Select will create for you when adding a tag. It should return a value that has the same properties as the rest of your options.

If you don't define createOption, Vue Select will construct a simple object following this structure: {[this.label]: searchText}. If you're using reduce, this is probably not what your options look like, which is why you'll need to set the function yourself.

Example

We have a taggable select for adding books to a collection. We're just concerned about getting the book title added, and our server side code will add the author details in a background process. The user has already selected a book.

const options = [
  {
    title: "HTML5",
    author: {
      firstName: "Remy",
      lastName: "Sharp"
    }
  }
];

<v-select
  taggable
  multiple
  label="title"
  :options="options"
  :create-option="book => ({ title: book, author: { firstName: '', lastName: '' } })"
  :reduce="book => `${book.author.firstName} ${book.author.lastName}`"
/>