Skip to content

Commit db43a67

Browse files
author
Jeff
committed
overhaul selecting docs, updated navigation and URL structure
1 parent 38baaf3 commit db43a67

File tree

13 files changed

+208
-96
lines changed

13 files changed

+208
-96
lines changed

‎docs/.vuepress/components/CountrySelect.vue

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
<template>
2+
<v-select :options="options"></v-select>
3+
</template>
4+
5+
<script>
6+
import countryCodes from '../data/countryCodes';
7+
8+
export default {
9+
name: 'CountrySelect',
10+
data: () => ({
11+
options: countryCodes,
12+
}),
13+
};
14+
</script>
15+
16+
<style scoped>
17+
18+
</style>

‎docs/.vuepress/components/ReducerNestedValue.vue

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<template>
2+
<div class="flex">
3+
<div>
4+
<v-select
5+
label="country"
6+
v-model="selected"
7+
:reduce="opt => opt.meta.id"
8+
:options="options"
9+
/>
10+
</div>
11+
<div>
12+
<pre><code>v-model value: {{ selected || 'null' }}</code></pre>
13+
</div>
14+
</div>
15+
</template>
16+
17+
<script>
18+
export default {
19+
name: 'ReducerNestedValue',
20+
data: () => ({
21+
selected: null,
22+
options: [
23+
{
24+
country: 'canada',
25+
meta: {
26+
id: '1',
27+
code: 'ca',
28+
},
29+
}],
30+
}),
31+
};
32+
</script>
33+
34+
<style scoped>
35+
.flex {
36+
margin-bottom: 2rem;
37+
border: 1px solid #eaecef;
38+
/*padding: 1rem;*/
39+
display: flex;
40+
justify-content: center;
41+
align-items: center;
42+
}
43+
44+
.flex > div {
45+
flex-grow: 1;
46+
width: 50%;
47+
padding: 0 1rem;
48+
}
49+
50+
pre {
51+
margin: 0;
52+
background: #fff;
53+
}
54+
55+
code {
56+
color: #635762 !important;
57+
color: #5b2d2d !important;
58+
/*color: #7ec699 !important;*/
59+
}
60+
</style>

‎docs/.vuepress/config.js

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -74,19 +74,19 @@ module.exports = {
7474
title: 'Getting Started',
7575
collapsable: false,
7676
children: [
77-
['getting-started/install', 'Installation'],
78-
['getting-started/options', 'Dropdown Options'],
79-
['getting-started/values', 'Selecting Values'],
80-
['getting-started/localization', 'Localization'],
77+
['guide/install', 'Installation'],
78+
['guide/options', 'Dropdown Options'],
79+
['guide/values', 'Selecting Values'],
80+
['guide/localization', 'Localization'],
8181
],
8282
},
8383
{
8484
title: 'Digging Deeper',
8585
collapsable: false,
8686
children: [
87-
['digging-deeper/templating', 'Templating & Slots'],
88-
['digging-deeper/vuex', 'Vuex'],
89-
['digging-deeper/ajax', 'AJAX'],
87+
['guide/templating', 'Templating & Slots'],
88+
['guide/vuex', 'Vuex'],
89+
['guide/ajax', 'AJAX'],
9090
],
9191
},
9292
{

‎docs/getting-started/values.md

Lines changed: 0 additions & 79 deletions
This file was deleted.

‎docs/digging-deeper/ajax.md renamed to ‎docs/guide/ajax.md

File renamed without changes.

‎docs/digging-deeper/examples.md renamed to ‎docs/guide/examples.md

File renamed without changes.

‎docs/getting-started/install.md renamed to ‎docs/guide/install.md

File renamed without changes.

‎docs/getting-started/localization.md renamed to ‎docs/guide/localization.md

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -39,5 +39,3 @@ All of the text within the component has been wrapped within [slots](https://vue
3939
```
4040

4141
For a full list of component slots, view the [slots API docs](../api/slots.md).
42-
43-
<CodePen url="oZmLVN" height="450"/>

‎docs/digging-deeper/mixins.md renamed to ‎docs/guide/mixins.md

File renamed without changes.

‎docs/getting-started/options.md renamed to ‎docs/guide/options.md

Lines changed: 16 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,24 +6,30 @@
66

77
```html
88
<!-- array of strings or numbers -->
9+
<v-select :options="['foo','bar']"></v-select>
10+
```
11+
912
<v-select :options="['foo','bar']"></v-select>
1013

14+
```html
1115
<!-- or, an array of objects -->
1216
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
1317
```
1418

19+
<v-select :options="[{label: 'foo', value: 'Foo'}]"></v-select>
20+
1521
## Option Labels
1622

17-
#### Option Primitives (strings, numbers)
23+
#### Options as Primitives (strings, numbers, boolean)
1824

1925
When `options` contains strings or numbers, they'll be used as the label for the option within the
2026
component. No further configuration is necessary.
2127

22-
#### Option Objects
28+
#### Options as Objects
2329

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.
30+
When `options` is an array of objects, the component must generate a label to be shown as the
31+
options text. By default, `vue-select` will attempt to render `option.label` as the option label.
32+
You can set your own label to match your source data using the `label` prop.
2733

2834
For example, consider an object with `countryCode` and `countryName` properties:
2935

@@ -40,15 +46,17 @@ If you wanted to display `Canada` in the dropdown, you'd use the `countryName` k
4046
<v-select label="countryName" :options="countries"></v-select>
4147
```
4248

43-
<CodePen url="aEjLPB" height="450"/>
49+
<country-select />
4450

4551
## Null / Empty Options
4652

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 `[]`.
53+
`vue-select` requires the `option` property to be an `array`. If you are using Vue in development
54+
mode, you will get warnings attempting to pass anything other than an `array` to the `options` prop.
55+
If you need a `null`/`empty` value, use an empty array `[]`.
4856

4957
## Tagging
5058

5159
To allow input that's not present within the options, set the `taggable` prop to true.
5260
If you want new tags to be pushed to the options list, set `push-tags` to true.
5361

54-
<CodePen url="XVoWxm" height="350"/>
62+
<v-select taggable />

‎docs/digging-deeper/templating.md renamed to ‎docs/guide/templating.md

File renamed without changes.

‎docs/guide/values.md

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
## Getting / Setting
2+
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. The `v-model` syntax works with
7+
primitives and objects.
8+
9+
```html
10+
<v-select v-model="selected" />
11+
```
12+
13+
Note that when using the `multiple` prop, the `v-model` value will always be an array.
14+
15+
### Props and Events
16+
17+
Sometimes `v-model` might not fit your use case. For example, when working with [Vuex](https://vuex.vuejs.org),
18+
you'll need to trigger a mutation rather than mutating a value directly. In that case, maybe you need
19+
to bind a pre-selected value, and trigger a mutation when it changes.
20+
21+
vue-select exposes the `value` prop and an `input` event to enable this. This combo of props and
22+
events is also how Vue wires up the `v-model` syntax internally.
23+
24+
#### Prop: `value`
25+
26+
The `value` prop lets vue-select know what value is currently selected. It will accept strings,
27+
numbers or objects. If you're using a `multiple` v-select, you'll want to pass an array.
28+
29+
```html
30+
<v-select :value="selected" />
31+
```
32+
33+
::: tip 🤓
34+
Anytime you bind the `value` prop directly, you're responsible for updating the bound variable
35+
in your code using the `@input` event.
36+
:::
37+
38+
#### Event: `input`
39+
40+
The `input` event is triggered anytime the value state changes, and is emitted with the `value`
41+
state as it's only parameter.
42+
43+
#### Vuex Support
44+
45+
The `value` prop and `emit` event are very useful when using a state management tool, like Vuex.
46+
You can bind the selected value with `:value="$store.myValue"`, and use the `input` event to
47+
trigger a mutation, or dispatch an action – or anything else you might need to do when the selection
48+
changes.
49+
50+
```html
51+
<v-select :value="$store.myValue" @input="setSelected" />
52+
```
53+
54+
```js
55+
methods: {
56+
setSelected(value) {
57+
// trigger a mutation, or dispatch an action
58+
}
59+
}
60+
```
61+
## Transforming Selections
62+
63+
When the `options` array contains objects, vue-select returns the whole object as dropdown value upon selection.
64+
65+
If you need to return a single key, or transform the data before it is synced, vue-select provides a `reduce` callback
66+
that allows you to transform a selected option before it is passed to the `@input` event. Consider this data structure:
67+
68+
```js
69+
let options = [{code: 'CA', country: 'Canada'}, ...];
70+
```
71+
72+
If we want to display the `country`, but return the `code` to `v-model`, we can use the `reduce` prop to receive
73+
only the data that's required.
74+
75+
```html
76+
<v-select :options="options" :reduce="country => country.code" label="country" />
77+
```
78+
79+
The `reduce` property also works well when you have a deeply nested value:
80+
81+
```
82+
{
83+
country: 'canada',
84+
meta: {
85+
id: '1',
86+
code: 'ca'
87+
}
88+
}
89+
```
90+
91+
```html
92+
<v-select :options="options" :reduce="country => country.value.id" label="country" />
93+
```
94+
95+
<reducer-nested-value />
96+
97+
## Single/Multiple Selection
98+
99+
By default, vue-select supports choosing a single value. If you need multiple values, use the `multiple` boolean prop,
100+
much the same way you would on a native `<select>` element. When `multiple` is true, `v-model` or `value` should be
101+
arrays.
102+
103+
104+
```html
105+
<v-select multiple v-model="selected" :options="['foo','bar']" />
106+
```
107+
<v-select multiple :options="['foo','bar']" />

‎docs/digging-deeper/vuex.md renamed to ‎docs/guide/vuex.md

File renamed without changes.

0 commit comments

Comments
 (0)