|
13 | 13 | +subsection('Single select (object)') |
14 | 14 | :markdown-it |
15 | 15 | When working with objects, you must provide additional props: `label` and `track-by`. |
16 | | - |
| 16 | + |
17 | 17 | `track-by` is used to identify the option within the options list thus it’s value has to be unique. In this example the `name` property is unique across all options, so it can be used as `track-by` value. |
18 | | - |
| 18 | + |
19 | 19 | `label` is used to display the option. |
20 | | - |
| 20 | + |
21 | 21 | #### Optional configuration flags: |
22 | 22 | - `:searchable="false"` – disables the search functionality |
23 | 23 | - `:allow-empty="false"` – once there is a value it can’t be deselected |
24 | 24 | - `deselect-label="Can't remove this value"` – when highlighted, the already selected option will have the _Can't remove this value_ helper label. Useful for single selects that don’t allow empty selection. |
25 | 25 | +example('SingleSelectObject') |
26 | | - +subsection('Select with search') |
27 | | - :markdown-it |
28 | | - By default `searchable` is set to true, thus using search doesn’t require any prop. |
29 | | - |
30 | | - The internal search engine is based on the `label` prop. In other words – when searching, vue-multiselect only compares the option labels with the current search query. If you want to search inside other object properties look at the [ajax search example](#sub-asynchronous-select). |
31 | | - |
32 | | - `custom-label` accepts a function with the `option` object as the first param. It should return a string which is then used to display a custom label. |
33 | | - +example('SingleSelectSearch') |
34 | | - +subsection('Multiple select') |
35 | | - :markdown-it |
36 | | - To allow multiple selections pass the `:multiple="true"` prop. |
37 | | - |
38 | | - #### Optional configuration flags: |
39 | | - - `:close-on-select="false"` – the dropdown stays open after selecting an option |
40 | | - - `:hide-selected="true"` – already selected options will not be displayed in the dropdown |
41 | | - - `:clear-on-select="false"` – the search query stays the same after selecting an option |
42 | | - #### New in v2.0.0 stable: |
43 | | - - You can now pass `<template slot="tag" slot-scope="props"><Your code></template>` to use a different markup for selected options (tags) |
44 | | - +example('MultiSelect') |
45 | | - +subsection('Asynchronous select') |
46 | | - :markdown-it |
47 | | - Vue-Multiselect supports changing the option list on the fly, thus can be also used a type-a-head search box. |
48 | | - |
49 | | - To react to the search query changes, set a handler function on the `@search-change` event. It receives the `searchQuery` as the first param, which can be used to make an asynchronous API call. |
50 | | - |
51 | | - It is convenient to set the `:loading` prop to `true`, whenever a request is in progress. Look at the provided `asyncFind` method for an example usage. |
52 | | - |
53 | | - #### Optional configuration flags: |
54 | | - - `:internal-search="false"` – disables the multiselect’s internal search engine. If you do that, you have to manually update the available `:options`. |
55 | | - - `:limit="3"` – limits the visible results to 3. |
56 | | - - `:limit-text="limitText"` – function that receives the current selected options count and should return a string to show when the `:limit` count is exceed |
57 | | - - `:options-limit="300"` – limits the displayed options to `300`. Useful for optimisations purposes. |
58 | | - |
59 | | - #### New in v2.0.0 stable: |
60 | | - - `id="ajax"` – every event is emitted with this as the second param. Useful for identification which component instance triggered the method (in loops for example). NEW: Can also be used for pointing with `<label :for="id">`. |
61 | | - - `open-direction="bottom"` – forces the multiselect to always open below. Use `top` or `above` to always open above. By default the multiselect will open whereever there is more space once there is not enough space below to open at `maxHeight`. |
62 | | - +example('AjaxSearch') |
63 | | - +subsection('Tagging') |
64 | | - :markdown-it |
65 | | - To add tagging functionality to single/multiple selects, set the `:taggable` prop to `true`. This will add an additional option at the beginning of the options list whenever you type a phrase that doesn’t have an exact match in the available options. Selecting this temporary option will emit the `@tag` event with the current typed search query as the first param. The event handler should add the received **tag** to both the options list and the value. |
66 | | - |
67 | | - Remember that when working with objects as options, you have to transform the received tag string to an object that matches the objects structure of the options list. In this example, the `addTag` method generates an object with a unique `code` property. |
68 | | - |
69 | | - #### Optional configuration flags: |
70 | | - - `tag-placeholder="Add this as new tag"` – A helper label that will be displayed when highlighting the just typed tag suggestion. |
71 | | - - `tag-position="bottom"` – By default the tag position will be set to 'top' and new tags will appear above the search results. Changing the tag positon to 'bottom' will revert this behaviour and will prioritize the search results. |
72 | | - +example('Tagging') |
73 | | - +subsection('Custom option template') |
74 | | - :markdown-it |
75 | | - You can use `option` [scoped slot](https://vuejs.org/v2/guide/components.html#Scoped-Slots) to provide a custom option template. The available `props` include `props.option` and `props.search`. Look at the provided example for more details. |
76 | | - |
77 | | - To ensure the keyboard navigation works properly, remember to set the `:option-height` so it equals the height of the option template. By default, the component assumes an option height of 40px. |
78 | | - |
79 | | - #### Optional configuration flags: |
80 | | - - `:option-height="104"` – The height of the custom option template. |
81 | | - +example('CustomOption') |
82 | | - +subsection('Option groups') |
83 | | - :markdown-it |
84 | | - The options list can also contain groups. It requires passing 3 additional props: `group-label`, `group-values` and `group-select`. `group-label` is used to locate the group label. `group-values` should point to the group’s option list. `group-select` is used to define if selecting the group label should select/unselect all values in the group, or do nothing. |
85 | | - |
86 | | - Despite that the available options are grouped, the selected options are stored as a flat array of objects. |
87 | | - |
88 | | - Please look at the provided example for a example options list structure. |
89 | | - +example('Groups') |
90 | | - +subsection('Vuex support') |
91 | | - :markdown-it |
92 | | - Due to the one-way data-flow enforced by Vuex you should not be using `v-model` for manipulating the currently selected value. |
93 | | - Because Vue-Multiselect always uses it’s own internal copy of the value it never mutates the `:value` by itself, which means it can can safely used with Vuex or even Redux. |
94 | | - |
95 | | - In Vue 2.0 `v-model` is just a syntax sugar for `:value` and `@input`. Because of this we can use the `@input` event to trigger Vuex actions or mutations. Whenever we mutate the `:value` in Vuex, Multiselect’s internal value will update. |
96 | | - +example('VuexActions') |
97 | | - +subsection('Action dispatcher') |
98 | | - :markdown-it |
99 | | - The component may also act as dispatcher for different actions/methods. In this case there is no need for the `:value` prop. |
100 | | - Instead of `@input` you can listen on the `@select` event. The difference between the two is that `@select` only receives the currently selected value instead of the whole list of selected values (if select is multiple). |
101 | | - |
102 | | - #### Optional configuration flags: |
103 | | - - `:reset-after="true"` – Resets the internal value after each select action inside the component. |
104 | | - +example('ActionDispatcher') |
105 | | - +subsection('Custom configuration') |
106 | | - :markdown-it |
107 | | - Shows error when touched, but nothing is selected. |
108 | | - |
109 | | - #### Optional configuration flags: |
110 | | - - `:max-height="150"` – Set the dropdown height to 150px |
111 | | - - `:max="3"` – Set the maximal number of selections |
112 | | - - `:allow-empty="false"` – Doesn’t allow to remove the last option if it exists |
113 | | - - `:block-keys="['Tab', 'Enter']"` – Block the `Tab` and `Enter` keys from triggering their default behaviour |
114 | | - - `@close="onTouch"` – Event emitted when closing the dropdown |
115 | | - +example('CustomConfig') |
| 26 | + //- +subsection('Select with search') |
| 27 | + //- :markdown-it |
| 28 | + //- By default `searchable` is set to true, thus using search doesn’t require any prop. |
| 29 | + //- |
| 30 | + //- The internal search engine is based on the `label` prop. In other words – when searching, vue-multiselect only compares the option labels with the current search query. If you want to search inside other object properties look at the [ajax search example](#sub-asynchronous-select). |
| 31 | + //- |
| 32 | + //- `custom-label` accepts a function with the `option` object as the first param. It should return a string which is then used to display a custom label. |
| 33 | + //- +example('SingleSelectSearch') |
| 34 | + //- +subsection('Multiple select') |
| 35 | + //- :markdown-it |
| 36 | + //- To allow multiple selections pass the `:multiple="true"` prop. |
| 37 | + //- |
| 38 | + //- #### Optional configuration flags: |
| 39 | + //- - `:close-on-select="false"` – the dropdown stays open after selecting an option |
| 40 | + //- - `:hide-selected="true"` – already selected options will not be displayed in the dropdown |
| 41 | + //- - `:clear-on-select="false"` – the search query stays the same after selecting an option |
| 42 | + //- #### New in v2.0.0 stable: |
| 43 | + //- - You can now pass `<template slot="tag" slot-scope="props"><Your code></template>` to use a different markup for selected options (tags) |
| 44 | + //- +example('MultiSelect') |
| 45 | + //- +subsection('Asynchronous select') |
| 46 | + //- :markdown-it |
| 47 | + //- Vue-Multiselect supports changing the option list on the fly, thus can be also used a type-a-head search box. |
| 48 | + //- |
| 49 | + //- To react to the search query changes, set a handler function on the `@search-change` event. It receives the `searchQuery` as the first param, which can be used to make an asynchronous API call. |
| 50 | + //- |
| 51 | + //- It is convenient to set the `:loading` prop to `true`, whenever a request is in progress. Look at the provided `asyncFind` method for an example usage. |
| 52 | + //- |
| 53 | + //- #### Optional configuration flags: |
| 54 | + //- - `:internal-search="false"` – disables the multiselect’s internal search engine. If you do that, you have to manually update the available `:options`. |
| 55 | + //- - `:limit="3"` – limits the visible results to 3. |
| 56 | + //- - `:limit-text="limitText"` – function that receives the current selected options count and should return a string to show when the `:limit` count is exceed |
| 57 | + //- - `:options-limit="300"` – limits the displayed options to `300`. Useful for optimisations purposes. |
| 58 | + //- |
| 59 | + //- #### New in v2.0.0 stable: |
| 60 | + //- - `id="ajax"` – every event is emitted with this as the second param. Useful for identification which component instance triggered the method (in loops for example). NEW: Can also be used for pointing with `<label :for="id">`. |
| 61 | + //- - `open-direction="bottom"` – forces the multiselect to always open below. Use `top` or `above` to always open above. By default the multiselect will open whereever there is more space once there is not enough space below to open at `maxHeight`. |
| 62 | + //- +example('AjaxSearch') |
| 63 | + //- +subsection('Tagging') |
| 64 | + //- :markdown-it |
| 65 | + //- To add tagging functionality to single/multiple selects, set the `:taggable` prop to `true`. This will add an additional option at the beginning of the options list whenever you type a phrase that doesn’t have an exact match in the available options. Selecting this temporary option will emit the `@tag` event with the current typed search query as the first param. The event handler should add the received **tag** to both the options list and the value. |
| 66 | + //- |
| 67 | + //- Remember that when working with objects as options, you have to transform the received tag string to an object that matches the objects structure of the options list. In this example, the `addTag` method generates an object with a unique `code` property. |
| 68 | + //- |
| 69 | + //- #### Optional configuration flags: |
| 70 | + //- - `tag-placeholder="Add this as new tag"` – A helper label that will be displayed when highlighting the just typed tag suggestion. |
| 71 | + //- - `tag-position="bottom"` – By default the tag position will be set to 'top' and new tags will appear above the search results. Changing the tag positon to 'bottom' will revert this behaviour and will prioritize the search results. |
| 72 | + //- +example('Tagging') |
| 73 | + //- +subsection('Custom option template') |
| 74 | + //- :markdown-it |
| 75 | + //- You can use `option` [scoped slot](https://vuejs.org/v2/guide/components.html#Scoped-Slots) to provide a custom option template. The available `props` include `props.option` and `props.search`. Look at the provided example for more details. |
| 76 | + //- |
| 77 | + //- To ensure the keyboard navigation works properly, remember to set the `:option-height` so it equals the height of the option template. By default, the component assumes an option height of 40px. |
| 78 | + //- |
| 79 | + //- #### Optional configuration flags: |
| 80 | + //- - `:option-height="104"` – The height of the custom option template. |
| 81 | + //- +example('CustomOption') |
| 82 | + //- +subsection('Option groups') |
| 83 | + //- :markdown-it |
| 84 | + //- The options list can also contain groups. It requires passing 3 additional props: `group-label`, `group-values` and `group-select`. `group-label` is used to locate the group label. `group-values` should point to the group’s option list. `group-select` is used to define if selecting the group label should select/unselect all values in the group, or do nothing. |
| 85 | + //- |
| 86 | + //- Despite that the available options are grouped, the selected options are stored as a flat array of objects. |
| 87 | + //- |
| 88 | + //- Please look at the provided example for a example options list structure. |
| 89 | + //- +example('Groups') |
| 90 | + //- +subsection('Vuex support') |
| 91 | + //- :markdown-it |
| 92 | + //- Due to the one-way data-flow enforced by Vuex you should not be using `v-model` for manipulating the currently selected value. |
| 93 | + //- Because Vue-Multiselect always uses it’s own internal copy of the value it never mutates the `:value` by itself, which means it can can safely used with Vuex or even Redux. |
| 94 | + //- |
| 95 | + //- In Vue 2.0 `v-model` is just a syntax sugar for `:value` and `@input`. Because of this we can use the `@input` event to trigger Vuex actions or mutations. Whenever we mutate the `:value` in Vuex, Multiselect’s internal value will update. |
| 96 | + //- +example('VuexActions') |
| 97 | + //- +subsection('Action dispatcher') |
| 98 | + //- :markdown-it |
| 99 | + //- The component may also act as dispatcher for different actions/methods. In this case there is no need for the `:value` prop. |
| 100 | + //- Instead of `@input` you can listen on the `@select` event. The difference between the two is that `@select` only receives the currently selected value instead of the whole list of selected values (if select is multiple). |
| 101 | + //- |
| 102 | + //- #### Optional configuration flags: |
| 103 | + //- - `:reset-after="true"` – Resets the internal value after each select action inside the component. |
| 104 | + //- +example('ActionDispatcher') |
| 105 | + //- +subsection('Custom configuration') |
| 106 | + //- :markdown-it |
| 107 | + //- Shows error when touched, but nothing is selected. |
| 108 | + //- |
| 109 | + //- #### Optional configuration flags: |
| 110 | + //- - `:max-height="150"` – Set the dropdown height to 150px |
| 111 | + //- - `:max="3"` – Set the maximal number of selections |
| 112 | + //- - `:allow-empty="false"` – Doesn’t allow to remove the last option if it exists |
| 113 | + //- - `:block-keys="['Tab', 'Enter']"` – Block the `Tab` and `Enter` keys from triggering their default behaviour |
| 114 | + //- - `@close="onTouch"` – Event emitted when closing the dropdown |
| 115 | + //- +example('CustomConfig') |
0 commit comments