mirror of
https://github.com/tenrok/vue-select.git
synced 2026-06-10 07:52:23 +03:00
overhaul selecting docs, updated navigation and URL structure
This commit is contained in:
Jeff
@@ -0,0 +1,60 @@
|
||||
# AJAX Remote Option Loading
|
||||
|
||||
<CodePen url="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,4 @@
|
||||
### Codepen Collection
|
||||
|
||||
I've put together a collection of examples, including all the examples
|
||||
from this documentation site on [Codepen](https://codepen.io/collection/nrkgxV/#).
|
||||
@@ -0,0 +1,57 @@
|
||||
### Vue Compatibility
|
||||
- `vue 1.x` use `vue-select 1.x`
|
||||
|
||||
## Yarn / NPM
|
||||
Install with yarn:
|
||||
```bash
|
||||
yarn add vue-select
|
||||
```
|
||||
or, using NPM:
|
||||
```
|
||||
npm install vue-select
|
||||
```
|
||||
|
||||
Then, import and register the component:
|
||||
|
||||
```js
|
||||
import Vue from 'vue'
|
||||
import vSelect from 'vue-select'
|
||||
|
||||
// register component
|
||||
Vue.component('v-select', vSelect)
|
||||
```
|
||||
|
||||
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/#/).
|
||||
|
||||
```html
|
||||
<!-- include VueJS first -->
|
||||
<script src="https://unpkg.com/vue@latest"></script>
|
||||
|
||||
<!-- use the latest release -->
|
||||
<script src="https://unpkg.com/vue-select@latest"></script>
|
||||
<link rel="stylesheet" href="https://unpkg.com/vue-select@latest/dist/vue-select.css">
|
||||
<!-- or point to a specific release -->
|
||||
<script src="https://unpkg.com/vue-select@2.6.0"></script>
|
||||
<link rel="stylesheet" href="https://unpkg.com/vue-select@2.6.0/dist/vue-select.css">
|
||||
```
|
||||
Then register the component in your javascript:
|
||||
|
||||
```js
|
||||
Vue.component('v-select', VueSelect.VueSelect);
|
||||
```
|
||||
|
||||
<CodePen url="dJjzeP" />
|
||||
@@ -0,0 +1,41 @@
|
||||
## 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
|
||||
*Slot Definition:*
|
||||
```html
|
||||
<slot name="spinner">
|
||||
<div class="spinner" v-show="mutableLoading">Loading...</div>
|
||||
</slot>
|
||||
```
|
||||
*Implementation:*
|
||||
```html
|
||||
<v-select>
|
||||
<i slot="spinner" class="icon icon-spinner"></i>
|
||||
</v-select>
|
||||
```
|
||||
|
||||
### No Options Text
|
||||
*Slot Definition:*
|
||||
```html
|
||||
<slot name="no-options">Sorry, no matching options.</slot>
|
||||
```
|
||||
*Implementation:*
|
||||
```html
|
||||
<v-select>
|
||||
<div slot="no-options">No Options Here!</div>
|
||||
</v-select>
|
||||
```
|
||||
|
||||
For a full list of component slots, view the [slots API docs](../api/slots.md).
|
||||
@@ -0,0 +1,62 @@
|
||||
# Dropdown Options
|
||||
|
||||
## Options Prop
|
||||
|
||||
`vue-select` accepts arrays of primitive values or objects to use as options through the `options` prop:
|
||||
|
||||
```html
|
||||
<!-- array of strings or numbers -->
|
||||
<v-select :options="['foo','bar']"></v-select>
|
||||
```
|
||||
|
||||
<v-select :options="['foo','bar']"></v-select>
|
||||
|
||||
```html
|
||||
<!-- or, an array of objects -->
|
||||
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
|
||||
```
|
||||
|
||||
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
|
||||
|
||||
## Option Labels
|
||||
|
||||
#### Options as Primitives (strings, numbers, boolean)
|
||||
|
||||
When `options` contains strings or numbers, they'll be used as the label for the option within the
|
||||
component. No further configuration is necessary.
|
||||
|
||||
#### Options as 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:
|
||||
|
||||
```json
|
||||
{
|
||||
countryCode: "CA",
|
||||
countryName: "Canada"
|
||||
}
|
||||
```
|
||||
|
||||
If you wanted to display `Canada` in the dropdown, you'd use the `countryName` key:
|
||||
|
||||
```html
|
||||
<v-select label="countryName" :options="countries"></v-select>
|
||||
```
|
||||
|
||||
<country-select />
|
||||
|
||||
## 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.
|
||||
|
||||
<v-select taggable />
|
||||
@@ -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 url="NXBwYG" height="500"/>
|
||||
@@ -0,0 +1,107 @@
|
||||
## Getting / 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.
|
||||
|
||||
```html
|
||||
<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](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
|
||||
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.
|
||||
|
||||
```html
|
||||
<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.
|
||||
|
||||
```html
|
||||
<v-select :value="$store.myValue" @input="setSelected" />
|
||||
```
|
||||
|
||||
```js
|
||||
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.
|
||||
|
||||
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
|
||||
<v-select :options="options" :reduce="country => country.code" label="country" />
|
||||
```
|
||||
|
||||
The `reduce` property also works well when you have a deeply nested value:
|
||||
|
||||
```
|
||||
{
|
||||
country: 'canada',
|
||||
meta: {
|
||||
id: '1',
|
||||
code: 'ca'
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
<v-select :options="options" :reduce="country => country.value.id" label="country" />
|
||||
```
|
||||
|
||||
<reducer-nested-value />
|
||||
|
||||
## 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 a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
|
||||
arrays.
|
||||
|
||||
|
||||
```html
|
||||
<v-select multiple v-model="selected" :options="['foo','bar']" />
|
||||
```
|
||||
<v-select multiple :options="['foo','bar']" />
|
||||
@@ -0,0 +1,16 @@
|
||||
### 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
|
||||
@input="myAction"
|
||||
:options="$store.state.options"
|
||||
:value="$store.state.selected"
|
||||
></v-select>
|
||||
```
|
||||
|
||||
<CodePen url="aJQJyp" height="350"/>
|
||||
Reference in New Issue
Block a user