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 `