diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js
index f0bf51b..fe0f561 100644
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@@ -87,7 +87,6 @@ module.exports = {
['digging-deeper/templating', 'Templating & Slots'],
['digging-deeper/vuex', 'Vuex'],
['digging-deeper/ajax', 'AJAX'],
- ['digging-deeper/examples', 'Examples'],
],
},
{
diff --git a/docs/digging-deeper/ajax.md b/docs/digging-deeper/ajax.md
index 9d0e323..c03ee4c 100644
--- a/docs/digging-deeper/ajax.md
+++ b/docs/digging-deeper/ajax.md
@@ -1,4 +1,4 @@
-## AJAX Remote Option Loading
+# AJAX Remote Option Loading
diff --git a/docs/getting-started/install.md b/docs/getting-started/install.md
index 1eaa30c..042dea1 100644
--- a/docs/getting-started/install.md
+++ b/docs/getting-started/install.md
@@ -1,6 +1,5 @@
### Vue Compatibility
-- `vue ~2.0` use `vue-select ~2.0`
-- `vue ~1.0` use `vue-select ~1.0`
+- `vue 1.x` use `vue-select 1.x`
## Yarn / NPM
Install with yarn:
@@ -18,10 +17,23 @@ Then, import and register the component:
import Vue from 'vue'
import vSelect from 'vue-select'
+// register component
Vue.component('v-select', vSelect)
```
-## CDN
+The component itself does not include any CSS. You'll need to include it separately:
+
+```js
+import 'vue-select/dist/vue-select.css';
+```
+
+You can also import the scss yourself for complete control of the component styles:
+
+```scss
+@import "vue-select/src/scss/vue-select.scss";
+```
+
+## In the Browser / CDN
Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.com/#/).
@@ -31,8 +43,10 @@ Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.co
+
-
+
+
```
Then register the component in your javascript:
diff --git a/docs/getting-started/options.md b/docs/getting-started/options.md
index 7aff972..88428f9 100644
--- a/docs/getting-started/options.md
+++ b/docs/getting-started/options.md
@@ -1,20 +1,29 @@
# Dropdown Options
-`vue-select` accepts arrays of strings or objects to use as options through the `options` prop:
+## Options Prop
+
+`vue-select` accepts arrays of primitive values or objects to use as options through the `options` prop:
```html
+
-```
-When provided an array of objects, `vue-select` will display a single value of the object. By default, `vue-select` will look for a key named `label` on the object to use as display text.
-
-```html
+
```
## Option Labels
-When the `options` array contains objects, `vue-select` looks for the `label` key to display by default. You can set your own label to match your source data using the `label` prop.
+#### Option Primitives (strings, numbers)
+
+When `options` contains strings or numbers, they'll be used as the label for the option within the
+component. No further configuration is necessary.
+
+#### Option Objects
+
+When `options` is an array of objects, the component must generate a label to be shown as the options text. By default,
+`vue-select` will attempt to render `option.label` as the option label. You can set your own label to match your
+source data using the `label` prop.
For example, consider an object with `countryCode` and `countryName` properties:
@@ -33,26 +42,13 @@ If you wanted to display `Canada` in the dropdown, you'd use the `countryName` k
-
-## Option Object Key
-
-When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection. You can specify your own `index` prop to return only the value contained in the specific property.
-
-For example, consider an object with `value` and `label` properties:
-
-```json
-{
- value: "CA",
- label: "Canada"
-}
-```
-
-If you wanted to return `CA` in the dropdown when `Canada` is selected, you'd use the `index` key:
-
-```html
-
-```
-
## Null / Empty Options
`vue-select` requires the `option` property to be an `array`. If you are using Vue in development mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop. If you need a `null`/`empty` value, use an empty array `[]`.
+
+## Tagging
+
+To allow input that's not present within the options, set the `taggable` prop to true.
+If you want new tags to be pushed to the options list, set `push-tags` to true.
+
+
diff --git a/docs/getting-started/values.md b/docs/getting-started/values.md
index 5b0fc1c..91d054f 100644
--- a/docs/getting-started/values.md
+++ b/docs/getting-started/values.md
@@ -1,53 +1,79 @@
-# Selecting Values
+## Getting / Setting
-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.
+### `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.
```html
-
+
```
-
+### `value` prop & `input` event
-If you don't require the `value` to be synced, you can also pass the prop directly:
+If you don't require the `value` to be synced, but you need to preselect a value, you can use the `value` prop. It will
+accept strings, numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array.
```html
-
+
```
-This method allows you to pre-select a value(s), without syncing any changes to the parent component. This is also very useful when using a state management tool, like Vuex.
+The `value` prop is very useful when using a state management tool, like Vuex. `vue-select` will emit an `input` event
+any time a value changes.
+
+```html
+
+```
+
+```js
+methods: {
+ setSelected(value) {
+ // do something with selected value
+ }
+}
+```
+## Transforming Selections
+
+When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection.
+
+If you need to return a single key, or transform the data 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:
+
+ ```js
+ 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.
+
+ ```html
+
+ ```
+
+The `reduce` property also works well when you have a deeply nested value:
+
+ ```
+ {
+ country: 'canada',
+ meta: {
+ id: '1',
+ code: 'ca'
+ }
+ }
+ ```
+
+ ```html
+
+ ```
## Single/Multiple Selection
-By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` prop:
+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 a native `