mirror of
https://github.com/tenrok/vue-select.git
synced 2026-05-17 02:29:37 +03:00
- complete docs overhaul
This commit is contained in:
Jeff
@@ -0,0 +1,60 @@
|
||||
## AJAX Remote Option Loading
|
||||
|
||||
[](codepen://sagalbot/POMeOX?height=400)
|
||||
|
||||
The `onSearch` prop allows you to load options via ajax in a parent component
|
||||
when the search text is updated. It is invoked with two parameters, `search` & `loading`.
|
||||
|
||||
```js
|
||||
/**
|
||||
* Accepts a callback function that will be run
|
||||
* when the search text changes. The callback
|
||||
* will be invoked with these parameters:
|
||||
*
|
||||
* @param {search} String Current search text
|
||||
* @param {loading} Function Toggle loading class
|
||||
*/
|
||||
onSearch: {
|
||||
type: Function,
|
||||
default: false
|
||||
},
|
||||
```
|
||||
|
||||
The `loading` function accepts a boolean parameter that will be assigned
|
||||
to the vue-select internal `loading` property. Call `loading(true)` to set the
|
||||
`loading` property to `true` - toggling the loading spinner. After your
|
||||
asynchronous operation completes, call `loading(false)` to toggle it off.
|
||||
|
||||
#### Disabling Filtering
|
||||
|
||||
When loading server side options, it can be useful to disable the
|
||||
client side filtering. Use the `filterable` prop to disable filtering.
|
||||
|
||||
```js
|
||||
/**
|
||||
* 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 Spinner
|
||||
|
||||
Vue Select includes a default loading spinner that appears when the loading class is present. The `spinner` slot allows you to implement your own spinner.
|
||||
|
||||
```html
|
||||
<div class="spinner" v-show="spinner">Loading...</div>
|
||||
```
|
||||
|
||||
#### Library Agnostic
|
||||
|
||||
Since Vue.js does not ship with ajax functionality as part of the core library, it's up to you to process the ajax requests in your parent component.
|
||||
|
||||
I recommend using [axios](https://github.com/axios/axios) for creating your applications HTTP layer,
|
||||
or [`fetch()`](https://github.com/github/fetch) for simple requests.
|
||||
|
||||
@@ -0,0 +1,17 @@
|
||||
#### Scoped Slot `option`
|
||||
|
||||
vue-select provides the scoped `option` slot in order to create custom dropdown templates.
|
||||
|
||||
```html
|
||||
<v-select :options="options" label="title">
|
||||
<template slot="option" slot-scope="option">
|
||||
<span :class="option.icon"></span>
|
||||
{{ option.title }}
|
||||
</template>
|
||||
</v-select>
|
||||
```
|
||||
|
||||
Using the `option` slot with `slot-scope="option"` gives the
|
||||
provides the current option variable to the template.
|
||||
|
||||
[](codepen://sagalbot/NXBwYG?height=500)
|
||||
@@ -0,0 +1 @@
|
||||
[](codepen://sagalbot/zZQJKW?height=600)
|
||||
@@ -1,18 +1,16 @@
|
||||
### Change Event <small>Vuex Compatibility</small>
|
||||
|
||||
`vue-select` provides a `change` event. This function is passed the currently selected value(s) as it's only parameter.
|
||||
|
||||
This is very useful when integrating with Vuex, as it will allow your to trigger an action to update your vuex state object. Choose a callback and see it in action.
|
||||
### Using the `input` Event with Vuex
|
||||
|
||||
`vue-select` emits the `input` event any time the internal `value` is changed.
|
||||
This is the same event that allow the for the `v-model` syntax. When using
|
||||
Vuex for state management, you can use the `input` event to dispatch an
|
||||
action, or trigger a mutation.
|
||||
|
||||
```html
|
||||
<v-select v-on:change="consoleCallback" :options="countries"></v-select>
|
||||
```
|
||||
<v-select
|
||||
@input="myAction"
|
||||
:options="$store.state.options"
|
||||
:value="$store.state.selected"
|
||||
></v-select>
|
||||
```
|
||||
|
||||
```js
|
||||
methods: {
|
||||
consoleCallback(val) {
|
||||
console.dir(JSON.stringify(val))
|
||||
},
|
||||
}
|
||||
```
|
||||
[](codepen://sagalbot/aJQJyp?height=500)
|
||||
@@ -1,31 +0,0 @@
|
||||
## AJAX Remote Option Loading
|
||||
|
||||
|
||||
The `onSearch` prop allows you to load options via ajax in a parent component when the search text is updated. It is invoked with two parameters, `search` & `loading`.
|
||||
|
||||
#### onSearch Callback Parameters <small>search, loading</small>
|
||||
|
||||
`search` is a string containing the current search text. `loading` is a function that accepts a boolean value, and is used to toggle the 'loading' class on the top-level vue-select wrapper.
|
||||
|
||||
#### Loading Spinner
|
||||
|
||||
Vue Select includes a default loading spinner that appears when the loading class is present. The `spinner` slot allows you to implement your own spinner.
|
||||
|
||||
<div id="spinner-example" :class="{loading:spinner}"><button class="btn btn-sm btn-default" @click="spinner = !spinner">Toggle Spinner</button>
|
||||
|
||||
<div class="spinner" v-show="spinner">Loading...</div>
|
||||
|
||||
#### Debounce Input
|
||||
|
||||
Vue Select also accepts a `debounce` prop that can be used to prevent `onSearch` from being called until input has completed.
|
||||
|
||||
#### Library Agnostic
|
||||
|
||||
Since Vue.js does not ship with ajax functionality as part of the core library, it's up to you to process the ajax requests in your parent component.
|
||||
|
||||
|
||||
#### Example <small>GitHub API</small>
|
||||
|
||||
In this example, [Vue Resource](https://github.com/vuejs/vue-resource) is used to access the [GitHub API](https://developer.github.com/v3/).
|
||||
|
||||
<git-hub-search-basic></git-hub-search-basic><ajax-example></ajax-example></div>
|
||||
|
||||
@@ -1,28 +0,0 @@
|
||||
```html
|
||||
<v-select
|
||||
:debounce="250"
|
||||
:on-search="getOptions"
|
||||
:options="options"
|
||||
placeholder="Search GitHub Repositories..."
|
||||
label="full_name"
|
||||
>
|
||||
</v-select>
|
||||
```
|
||||
```js
|
||||
data() {
|
||||
return {
|
||||
options: null
|
||||
}
|
||||
},
|
||||
methods: {
|
||||
getOptions(search, loading) {
|
||||
loading(true)
|
||||
this.$http.get('https://api.github.com/search/repositories', {
|
||||
q: search
|
||||
}).then(resp => {
|
||||
this.options = resp.data.items
|
||||
loading(false)
|
||||
})
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -1,24 +0,0 @@
|
||||
```js
|
||||
/**
|
||||
* Accept a callback function that will be run
|
||||
* when the search text changes. The callback
|
||||
* will be invoked with these parameters:
|
||||
|
||||
* @param {search} String Current search text
|
||||
* @param {loading} Function(bool) Toggle loading class
|
||||
*/
|
||||
onSearch: {
|
||||
type: Function,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Milliseconds to wait before invoking this.onSearch().
|
||||
* Used to prevent sending an AJAX request until input
|
||||
* has completed.
|
||||
*/
|
||||
debounce: {
|
||||
type: Number,
|
||||
default: 0
|
||||
}
|
||||
```
|
||||
|
||||
+290
-6
@@ -1,6 +1,290 @@
|
||||
{%
|
||||
includeCsv
|
||||
src="./props.csv",
|
||||
linkSrc="false",
|
||||
useHeader="true"
|
||||
%}{% endincludeCsv %}
|
||||
## Select
|
||||
|
||||
```js
|
||||
/**
|
||||
* Contains the currently selected value. Very similar to a
|
||||
* `value` attribute on an <input>. You can listen for changes
|
||||
* using 'change' event using v-on
|
||||
* @type {Object||String||null}
|
||||
*/
|
||||
value: {
|
||||
default: null
|
||||
},
|
||||
|
||||
/**
|
||||
* 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: 'This is Foo', value: 'foo'}]). A
|
||||
* custom label key can be set with the `label` prop.
|
||||
* @type {Array}
|
||||
*/
|
||||
options: {
|
||||
type: Array,
|
||||
default() {
|
||||
return []
|
||||
},
|
||||
},
|
||||
|
||||
/**
|
||||
* Disable the entire component.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
disabled: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Sets the max-height property on the dropdown list.
|
||||
* @deprecated
|
||||
* @type {String}
|
||||
*/
|
||||
maxHeight: {
|
||||
type: String,
|
||||
default: '400px'
|
||||
},
|
||||
|
||||
/**
|
||||
* Enable/disable filtering the options.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
searchable: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
|
||||
/**
|
||||
* Equivalent to the `multiple` attribute on a `<select>` input.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
multiple: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Equivalent to the `placeholder` attribute on an `<input>`.
|
||||
* @type {String}
|
||||
*/
|
||||
placeholder: {
|
||||
type: String,
|
||||
default: ''
|
||||
},
|
||||
|
||||
/**
|
||||
* Sets a Vue transition property on the `.dropdown-menu`. vue-select
|
||||
* does not include CSS for transitions, you'll need to add them yourself.
|
||||
* @type {String}
|
||||
*/
|
||||
transition: {
|
||||
type: String,
|
||||
default: 'fade'
|
||||
},
|
||||
|
||||
/**
|
||||
* Enables/disables clearing the search text when an option is selected.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
clearSearchOnSelect: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
|
||||
/**
|
||||
* Close a dropdown when an option is chosen. Set to false to keep the dropdown
|
||||
* open (useful when combined with multi-select, for example)
|
||||
* @type {Boolean}
|
||||
*/
|
||||
closeOnSelect: {
|
||||
type: Boolean,
|
||||
default: true
|
||||
},
|
||||
|
||||
/**
|
||||
* Tells vue-select what key to use when generating option
|
||||
* labels when each `option` is an object.
|
||||
* @type {String}
|
||||
*/
|
||||
label: {
|
||||
type: String,
|
||||
default: 'label'
|
||||
},
|
||||
|
||||
/**
|
||||
* Callback to generate the label text. If {option}
|
||||
* is an object, returns option[this.label] by default.
|
||||
* @type {Function}
|
||||
* @param {Object || String} option
|
||||
* @return {String}
|
||||
*/
|
||||
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` +
|
||||
'http://sagalbot.github.io/vue-select/#ex-labels'
|
||||
)
|
||||
}
|
||||
if (this.label && option[this.label]) {
|
||||
return option[this.label]
|
||||
}
|
||||
}
|
||||
return option;
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* Callback to filter the search result the label text.
|
||||
* @type {Function}
|
||||
* @param {Object || String} option
|
||||
* @param {String} label
|
||||
* @param {String} search
|
||||
* @return {Boolean}
|
||||
*/
|
||||
filterFunction: {
|
||||
type: Function,
|
||||
default(option, label, search) {
|
||||
return (label || '').toLowerCase().indexOf(search.toLowerCase()) > -1
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* An optional callback function that is called each time the selected
|
||||
* value(s) change. When integrating with Vuex, use this callback to trigger
|
||||
* an action, rather than using :value.sync to retreive the selected value.
|
||||
* @type {Function}
|
||||
* @param {Object || String} val
|
||||
*/
|
||||
onChange: {
|
||||
type: Function,
|
||||
default: function (val) {
|
||||
this.$emit('input', val)
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* Enable/disable creating options from searchInput.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
taggable: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Set the tabindex for the input field.
|
||||
* @type {Number}
|
||||
*/
|
||||
tabindex: {
|
||||
type: Number,
|
||||
default: null
|
||||
},
|
||||
|
||||
/**
|
||||
* When true, newly created tags will be added to
|
||||
* the options list.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
pushTags: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* 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
|
||||
},
|
||||
|
||||
/**
|
||||
* User defined function for adding Options
|
||||
* @type {Function}
|
||||
*/
|
||||
createOption: {
|
||||
type: Function,
|
||||
default(newOption) {
|
||||
if (typeof this.mutableOptions[0] === 'object') {
|
||||
newOption = {[this.label]: newOption}
|
||||
}
|
||||
this.$emit('option:created', newOption)
|
||||
return newOption
|
||||
}
|
||||
},
|
||||
|
||||
/**
|
||||
* When false, updating the options will not reset the select value
|
||||
* @type {Boolean}
|
||||
*/
|
||||
resetOnOptionsChange: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Disable the dropdown entirely.
|
||||
* @type {Boolean}
|
||||
*/
|
||||
noDrop: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Sets the id of the input element.
|
||||
* @type {String}
|
||||
* @default {null}
|
||||
*/
|
||||
inputId: {
|
||||
type: String
|
||||
},
|
||||
|
||||
/**
|
||||
* Sets RTL support. Accepts 'ltr', 'rtl', 'auto'.
|
||||
* @see https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir
|
||||
* @type {String}
|
||||
* @default 'auto'
|
||||
*/
|
||||
dir: {
|
||||
type: String,
|
||||
default: 'auto'
|
||||
},
|
||||
```
|
||||
|
||||
## AJAX
|
||||
|
||||
```js
|
||||
/**
|
||||
* Toggles the adding of a 'loading' class to the main
|
||||
* .v-select wrapper. Useful to control UI state when
|
||||
* results are being processed through AJAX.
|
||||
*/
|
||||
loading: {
|
||||
type: Boolean,
|
||||
default: false
|
||||
},
|
||||
|
||||
/**
|
||||
* Accept a callback function that will be
|
||||
* run when the search text changes.
|
||||
*
|
||||
* loading() accepts a boolean value, and can
|
||||
* be used to toggle a loading class from
|
||||
* the onSearch callback.
|
||||
*
|
||||
* @param {search} String Current search text
|
||||
* @param {loading} Function(bool) Toggle loading class
|
||||
*/
|
||||
onSearch: {
|
||||
type: Function,
|
||||
default: function(search, loading){}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
+25
-25
@@ -1,25 +1,25 @@
|
||||
name,type,default
|
||||
value,Object || String || null,
|
||||
options,Array,
|
||||
disabled,Boolean,
|
||||
maxHeight,String,
|
||||
searchable,Boolean,
|
||||
multiple,Boolean,
|
||||
placeholder,String,
|
||||
transition,String,
|
||||
clearSearchOnSelect,Boolean,
|
||||
closeOnSelect,Boolean,
|
||||
label,String,
|
||||
getOptionLabel,Function,
|
||||
filterFunction,Function,
|
||||
filter,Function,
|
||||
onChange,Function,
|
||||
taggable,Boolean,
|
||||
tabindex,Number,
|
||||
pushTags,Boolean,
|
||||
filterable,Boolean,
|
||||
createOption,Function,
|
||||
resetOnOptionsChange,Boolean,
|
||||
noDrop,Boolean,
|
||||
inputId,String,
|
||||
dir,String,
|
||||
name,type
|
||||
value,Object||String||null
|
||||
options,Array
|
||||
disabled,Boolean
|
||||
maxHeight,String
|
||||
searchable,Boolean
|
||||
multiple,Boolean
|
||||
placeholder,String
|
||||
transition,String
|
||||
clearSearchOnSelect,Boolean
|
||||
closeOnSelect,Boolean
|
||||
label,String
|
||||
getOptionLabel,Function
|
||||
filterFunction,Function
|
||||
filter,Function
|
||||
onChange,Function
|
||||
taggable,Boolean
|
||||
tabindex,Number
|
||||
pushTags,Boolean
|
||||
filterable,Boolean
|
||||
createOption,Function
|
||||
resetOnOptionsChange,Boolean
|
||||
noDrop,Boolean
|
||||
inputId,String
|
||||
dir,String
|
||||
|
@@ -1,6 +1,19 @@
|
||||
### RTL
|
||||
|
||||
vue-select supports RTL using the standard HTML API using the `dir` attribute.
|
||||
|
||||
```html
|
||||
<v-select dir="rtl"></v-select>
|
||||
```
|
||||
|
||||
The `dir` attribute accepts the same values as the [HTML spec](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/dir): `rtl`,`ltr`, and `auto`.
|
||||
|
||||
### Component Text
|
||||
|
||||
All of the text within the component has been wrapped within [slots](https://vuejs.org/v2/guide/components.html#Content-Distribution-with-Slots) and can be replaced in your app.
|
||||
|
||||
#### Loading Spinner
|
||||
|
||||
##### Loading Spinner
|
||||
|
||||
```html
|
||||
<slot name="spinner">
|
||||
@@ -8,10 +21,11 @@ All of the text within the component has been wrapped within [slots](https://vue
|
||||
</slot>
|
||||
```
|
||||
|
||||
#### No Options Text
|
||||
##### No Options Text
|
||||
|
||||
```html
|
||||
<slot name="no-options">Sorry, no matching options.</slot>
|
||||
```
|
||||
For a full list of component slots, view the [slots API docs](Api/Slots.md).
|
||||
|
||||
For a full list of component slots, view the [slots API docs](Api/Slots.md).
|
||||
[](codepen://sagalbot/oZmLVN?height=250)
|
||||
@@ -1,19 +1,4 @@
|
||||
- [HTML5 Validation](#validation)
|
||||
- [Vuex](#vuex)
|
||||
- [AJAX](#ajax)
|
||||
- [Dependent vSelects](#dependent)
|
||||
- [Custom Component with Mixins](#customComponent)
|
||||
### Codepen Collection
|
||||
|
||||
## HTML5 Validation {#validation}
|
||||
|
||||
|
||||
|
||||
## Vuex {#vuex}
|
||||
|
||||
[](codepen://sagalbot/aJQJyp?height=500)
|
||||
|
||||
## AJAX {#ajax}
|
||||
|
||||
## Dependent vSelects {#dependent}
|
||||
|
||||
## Custom Component with Mixins {#customComponent}
|
||||
I've put together a collection of examples, including all the examples
|
||||
from this documentation site on [Codepen](https://codepen.io/collection/nrkgxV/#).
|
||||
@@ -12,10 +12,9 @@
|
||||
|
||||
- Digging Deeper
|
||||
- [Templating](Advanced/Templating.md)
|
||||
- [Vuex](Basics.md#options)
|
||||
- [AJAX](Basics.md#options)
|
||||
- [Mixins](Basics.md#options)
|
||||
- [Validation](Basics.md#options)
|
||||
- [Vuex](Advanced/Vuex.md)
|
||||
- [AJAX](Advanced/Ajax.md)
|
||||
- [Validation](Advanced/Validation.md)
|
||||
- [Examples](Examples.md)
|
||||
|
||||
- API
|
||||
|
||||
Reference in New Issue
Block a user