diff --git a/docs/.vuepress/components/ReducedWithNoMatchingOption.vue b/docs/.vuepress/components/ReducedWithNoMatchingOption.vue new file mode 100644 index 0000000..d6e3daa --- /dev/null +++ b/docs/.vuepress/components/ReducedWithNoMatchingOption.vue @@ -0,0 +1,20 @@ + + + diff --git a/docs/guide/values.md b/docs/guide/values.md index 2d664ae..5a82bfd 100644 --- a/docs/guide/values.md +++ b/docs/guide/values.md @@ -2,11 +2,12 @@ ### `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. +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. ```html + ``` @@ -14,25 +15,26 @@ Note that when using the `multiple` prop, the `v-model` value will always be an ### Props and Events -Sometimes `v-model` might not fit your use case. For example, when working with [Vuex](https://vuex.vuejs.org), -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. +Sometimes `v-model` might not fit your use case. For example, when working +with [Vuex](https://vuex.vuejs.org), 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 +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. +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. ```html + ``` -::: tip 🤓 -Anytime you bind the `value` prop directly, you're responsible for updating the bound variable -in your code using the `@input` event. +::: 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` @@ -42,50 +44,66 @@ 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. +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. ```html + ``` ```js methods: { - setSelected(value) { - // trigger a mutation, or dispatch an action - } + setSelected(value) + { + // trigger a mutation, or dispatch an action + } } ``` + +## Single/Multiple + +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 `` element. When `multiple` -is true, `v-model` and `value` must be an array. - +The most common issue with `reduce` is when the component displays your _reduced_ _value_ instead of +it's _label_. This happens when you supply Vue Select a `value` or `v-model` binding with a reduced_ +value, but the complete option object is not present in the `options` array. -```html - -``` - + + +<<< @/.vuepress/components/ReducedWithNoMatchingOption.vue + +In the example above, the component was supplied with an ID that doesn't exist in the `options` +array. When `value` changes, Vue Select searches the supplied options, running each one +through `reduce` until the corresponding option is found. When that option doesn't exist, Vue Select +will end up displaying the `value` supplied. + +::: warning + +When providing Vue Select with a _reduced_ `value` - the object that the value was reduced from must +exist in the `options` array. + +::: ## Tagging To allow input that's not present within the options, set the `taggable` prop to true. ```html + ``` @@ -127,6 +157,7 @@ To allow input that's not present within the options, set the `taggable` prop to If you want added tags to be pushed to the options array, set `push-tags` to true. ```html + ``` @@ -136,10 +167,11 @@ If you want added tags to be pushed to the options array, set `push-tags` to tru 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 +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: +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. @@ -147,28 +179,29 @@ like, which is why you'll need to set the function yourself. 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. +user has already selected a book. ```js const options = [ - { - title: "HTML5", - author: { - firstName: "Remy", - lastName: "Sharp" + { + title: "HTML5", + author: { + firstName: "Remy", + lastName: "Sharp" + } } - } ]; ``` ```html + ```