Skip to content

Commit 699d595

Browse files
sagalbotsagalbot
authored
WIP: V3 - Remove index prop, add reduce prop (sagalbot#800)
* remove `index` in favour of `reduce`, tests passing * refactor findOptionFromReducedValue * - always use getOptionLabel in comparisons * - refactor deselect method - add missing jsdoc blocks - organize methods * bump documentation
1 parent e4d4b27 commit 699d595

File tree

7 files changed

+248
-221
lines changed

7 files changed

+248
-221
lines changed

‎docs/.vuepress/config.js

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,6 @@ module.exports = {
8787
['digging-deeper/templating', 'Templating & Slots'],
8888
['digging-deeper/vuex', 'Vuex'],
8989
['digging-deeper/ajax', 'AJAX'],
90-
['digging-deeper/examples', 'Examples'],
9190
],
9291
},
9392
{

‎docs/digging-deeper/ajax.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
## AJAX Remote Option Loading
1+
# AJAX Remote Option Loading
22

33
<CodePen url="POMeOX" height="400"/>
44

‎docs/getting-started/install.md

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
### Vue Compatibility
2-
- `vue ~2.0` use `vue-select ~2.0`
3-
- `vue ~1.0` use `vue-select ~1.0`
2+
- `vue 1.x` use `vue-select 1.x`
43

54
## Yarn / NPM
65
Install with yarn:
@@ -18,10 +17,23 @@ Then, import and register the component:
1817
import Vue from 'vue'
1918
import vSelect from 'vue-select'
2019

20+
// register component
2121
Vue.component('v-select', vSelect)
2222
```
2323

24-
## CDN
24+
The component itself does not include any CSS. You'll need to include it separately:
25+
26+
```js
27+
import 'vue-select/dist/vue-select.css';
28+
```
29+
30+
You can also import the scss yourself for complete control of the component styles:
31+
32+
```scss
33+
@import "vue-select/src/scss/vue-select.scss";
34+
```
35+
36+
## In the Browser / CDN
2537

2638
Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.com/#/).
2739

@@ -31,8 +43,10 @@ Include `vue` & `vue-select.js` - I recommend using [unpkg.com](https://unpkg.co
3143

3244
<!-- use the latest release -->
3345
<script src="https://unpkg.com/vue-select@latest"></script>
46+
<link rel="stylesheet" href="https://unpkg.com/vue-select@latest/dist/vue-select.css">
3447
<!-- or point to a specific release -->
35-
<script src="https://unpkg.com/vue-select@1.30"></script>
48+
<script src="https://unpkg.com/vue-select@2.6.0"></script>
49+
<link rel="stylesheet" href="https://unpkg.com/vue-select@2.6.0/dist/vue-select.css">
3650
```
3751
Then register the component in your javascript:
3852

‎docs/getting-started/options.md

Lines changed: 21 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,29 @@
11
# Dropdown Options
22

3-
`vue-select` accepts arrays of strings or objects to use as options through the `options` prop:
3+
## Options Prop
4+
5+
`vue-select` accepts arrays of primitive values or objects to use as options through the `options` prop:
46

57
```html
8+
<!-- array of strings or numbers -->
69
<v-select :options="['foo','bar']"></v-select>
7-
```
8-
9-
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.
1010

11-
```html
11+
<!-- or, an array of objects -->
1212
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
1313
```
1414

1515
## Option Labels
1616

17-
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.
17+
#### Option Primitives (strings, numbers)
18+
19+
When `options` contains strings or numbers, they'll be used as the label for the option within the
20+
component. No further configuration is necessary.
21+
22+
#### Option Objects
23+
24+
When `options` is an array of objects, the component must generate a label to be shown as the options text. By default,
25+
`vue-select` will attempt to render `option.label` as the option label. You can set your own label to match your
26+
source data using the `label` prop.
1827

1928
For example, consider an object with `countryCode` and `countryName` properties:
2029

@@ -33,26 +42,13 @@ If you wanted to display `Canada` in the dropdown, you'd use the `countryName` k
3342

3443
<CodePen url="aEjLPB" height="450"/>
3544

45+
## Null / Empty Options
3646

37-
## Option Object Key
38-
39-
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.
40-
41-
For example, consider an object with `value` and `label` properties:
42-
43-
```json
44-
{
45-
value: "CA",
46-
label: "Canada"
47-
}
48-
```
49-
50-
If you wanted to return `CA` in the dropdown when `Canada` is selected, you'd use the `index` key:
47+
`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 `[]`.
5148

52-
```html
53-
<v-select index="value" :options="countries"></v-select>
54-
```
49+
## Tagging
5550

56-
## Null / Empty Options
51+
To allow input that's not present within the options, set the `taggable` prop to true.
52+
If you want new tags to be pushed to the options list, set `push-tags` to true.
5753

58-
`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 `[]`.
54+
<CodePen url="XVoWxm" height="350"/>

‎docs/getting-started/values.md

Lines changed: 59 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -1,53 +1,79 @@
1-
# Selecting Values
1+
## Getting / Setting
22

3-
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.
3+
### `v-model`
4+
5+
The most common use case for `vue-select` is to have the chosen value synced with a parent component. `vue-select`
6+
takes advantage of the `v-model` syntax to sync values with a parent.
47

58
```html
6-
<v-select v-model="selected"></v-select>
9+
<v-select v-model="selected" />
710
```
811

9-
<CodePen url="Kqxbjw" height="250"/>
12+
### `value` prop & `input` event
1013

11-
If you don't require the `value` to be synced, you can also pass the prop directly:
14+
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
15+
accept strings, numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array.
1216

1317
```html
14-
<v-select :value="selected"></v-select>
18+
<v-select :value="selected" />
1519
```
1620

17-
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.
18-
19-
## Single/Multiple Selection
20-
21-
By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` prop:
21+
The `value` prop is very useful when using a state management tool, like Vuex. `vue-select` will emit an `input` event
22+
any time a value changes.
2223

2324
```html
24-
<v-select multiple v-model="selected"></v-select>
25+
<v-select :value="selected" @input="setSelected" />
2526
```
2627

27-
<CodePen url="opMGro" height="250"/>
28-
29-
## Tagging
30-
31-
To allow input that's not present within the options, set the `taggable` prop to true.
32-
If you want new tags to be pushed to the options list, set `push-tags` to true.
33-
34-
<CodePen url="XVoWxm" height="350"/>
35-
36-
## Return a Single Key from an Object
37-
38-
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.
39-
40-
For example, consider an object with `value` and `label` properties:
41-
42-
```json
43-
{
44-
value: "CA",
45-
label: "Canada"
28+
```js
29+
methods: {
30+
setSelected(value) {
31+
// do something with selected value
32+
}
4633
}
4734
```
35+
## Transforming Selections
36+
37+
When the `options` array contains objects, `vue-select` returns the whole object as dropdown value upon selection.
38+
39+
If you need to return a single key, or transform the data before it is synced, `vue-select` provides a `reduce` callback
40+
that allows you to transform a selected option before it is passed to the `@input` event. Consider this data structure:
41+
42+
```js
43+
let options = [{code: 'CA', country: 'Canada'}, ...];
44+
```
45+
46+
If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` prop to receive
47+
only the data that's required.
48+
49+
```html
50+
<v-select :options="options" :reduce="country => country.code" label="country" />
51+
```
52+
53+
The `reduce` property also works well when you have a deeply nested value:
54+
55+
```
56+
{
57+
country: 'canada',
58+
meta: {
59+
id: '1',
60+
code: 'ca'
61+
}
62+
}
63+
```
64+
65+
```html
66+
<v-select :options="options" :reduce="country => country.value.id" label="country" />
67+
```
68+
69+
## Single/Multiple Selection
4870

49-
If you wanted to return `CA` in the dropdown when `Canada` is selected, you'd use the `index` key:
71+
By default, `vue-select` supports choosing a single value. If you need multiple values, use the `multiple` boolean prop,
72+
much the same way you would on a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
73+
arrays.
74+
5075

5176
```html
52-
<v-select index="value" :options="countries"></v-select>
77+
<v-select multiple v-model="selected" :options="['foo','bar']" />
5378
```
79+
<v-select multiple :options="['foo','bar']" />

0 commit comments

Comments
 (0)