71 |
72 |
77 |
78 | ```
79 |
--------------------------------------------------------------------------------
/docs/demo/single-select.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Single Select'
3 | ---
4 |
5 | # Single Select
6 |
7 | The following example demonstrates how to use the `VueSelect` component to create a single select dropdown.
8 |
9 |
16 |
17 |
18 |
26 |
27 |
28 | Selected value: **{{ selected || "none" }}**
29 |
30 | ## Demo source-code
31 |
32 | ```vue
33 |
39 |
40 |
41 |
49 |
50 | ```
51 |
--------------------------------------------------------------------------------
/docs/events.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Events'
3 | ---
4 |
5 | # Events
6 |
7 | ## `@option-selected`
8 |
9 | Emitted when an option is selected, in the same tick where the `v-model` is updated.
10 |
11 | **Payload**: `Option` - The selected option.
12 |
13 | ```vue
14 |
15 |
20 |
21 | ```
22 |
23 | **Note**: this is emitted on the same tick as the v-model is updated, before a DOM re-render.
24 |
25 | ::: info
26 | For keeping track of the selected option, it's recommended to use a `computed` property combined with the `v-model` instead of relying on the `@option-selected` event. This approach is more efficient and aligns better with Vue's reactivity system. Here's an example:
27 |
28 | ```ts
29 | const options = [{ label: "France", value: "FR" }];
30 | const activeValue = ref("FR");
31 | const selectedOption = computed(
32 | () => options.find((option) => option.value === activeValue.value),
33 | );
34 | ```
35 | :::
36 |
37 | ## `@option-deselected`
38 |
39 | Emitted when an option is deselected, in the same tick where the `v-model` is updated.
40 |
41 | **Payload**: `Option` - The deselected option.
42 |
43 | ```vue
44 |
45 |
50 |
51 | ```
52 |
53 | **Note**: this is emitted on the same tick as the v-model is updated, before a DOM re-render.
54 |
55 | ## `@option-created`
56 |
57 | Emitted when a new option is created with the `:taggable="true"` prop.
58 |
59 | **Payload**: `string` - The search content value.
60 |
61 | ```vue
62 |
63 |
69 |
70 | ```
71 |
72 | ## `@search`
73 |
74 | Emitted when the search value is updated.
75 |
76 | **Payload**: `string` - The search content value.
77 |
78 | ::: warning
79 | Search value is cleared when the menu is closed. This will trigger an empty string emit event. See tests implementations for more details.
80 | :::
81 |
82 | ```vue
83 |
84 |
89 |
90 | ```
91 |
92 | ## `@menu-opened`
93 |
94 | Emitted when the menu is opened.
95 |
96 | ```vue
97 |
98 |
103 |
104 | ```
105 |
106 | ## `@menu-closed`
107 |
108 | Emitted when the menu is closed.
109 |
110 | ```vue
111 |
112 |
117 |
118 | ```
119 |
--------------------------------------------------------------------------------
/docs/getting-started.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Getting Started'
3 | ---
4 |
5 | # Getting Started
6 |
7 | ## Installation
8 |
9 | Vue 3 Select Component can be installed using your favorite package manager:
10 |
11 | ::: code-group
12 | ```sh [npm]
13 | $ npm add vue3-select-component
14 | ```
15 |
16 | ```sh [pnpm]
17 | $ pnpm add vue3-select-component
18 | ```
19 |
20 | ```sh [yarn]
21 | $ yarn add vue3-select-component
22 | ```
23 |
24 | ```sh [bun]
25 | $ bun add vue3-select-component
26 | ```
27 | :::
28 |
29 | ::: tip
30 | [Vue.js](https://vuejs.org) 3.5+ is required to use this component.
31 | :::
32 |
33 | ## Single select usage
34 |
35 | Import the component with the styling, and use it in your Vue 3 application:
36 |
37 | ```vue
38 |
44 |
45 |
46 |
55 |
56 | ```
57 |
58 | Since the component is built with TypeScript, your IDE will provide you with autocompletion and type checking automatically.
59 |
60 | ## Multiselect usage
61 |
62 | Import the component with the styling, and use it in your Vue 3 application.
63 |
64 | To enable the multiselect feature, all you need to do is:
65 |
66 | - set the `is-multi` prop to `true`
67 | - use an array for the `v-model`
68 |
69 | ```vue
70 |
76 |
77 |
86 | ```
87 |
88 | ## Data binding
89 |
90 | Vue 3 Select Component takes advantage of Vue's `v-model`, which means you can use it with `v-model` to bind the selected value(s) to a variable.
91 |
92 | This makes it easy to use the component anywhere in your application, while being reactive and easy to work with.
93 |
94 | [Learn more about `v-model`](https://vuejs.org/guide/components/v-model.html).
95 |
--------------------------------------------------------------------------------
/docs/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: home
3 |
4 | title: Vue 3 Select Component
5 | titleTemplate: The Selecting solution for Vue 3.
6 |
7 | hero:
8 | name: Vue 3 Select Component
9 | text: The Selecting solution for Vue 3.
10 | tagline: Best-in-class select component for Vue 3. Great DX, easy to use, and highly customizable.
11 | actions:
12 | - theme: brand
13 | text: Get Started
14 | link: /getting-started
15 | - theme: alt
16 | text: View on GitHub
17 | link: https://github.com/TotomInc/vue3-select-component
18 |
19 | features:
20 | - title: Best DX
21 | details: Built with TypeScript and Vue 3, the component provides a great developer experience with autocompletion and type checking.
22 | - title: Easy to Use
23 | details: The component leverage Vue's v-model to make it easy to use and integrate with your application.
24 | - title: Highly Customizable
25 | details: The component is highly customizable with a lot of options and slots to fit your needs.
26 | - title: Accessible
27 | details: The component is built with accessibility in mind and has been tested with screen readers.
28 | ---
29 |
--------------------------------------------------------------------------------
/docs/multiselect.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: home
3 |
4 | title: Vue 3 Multiselect Component
5 |
6 | head:
7 | - - meta
8 | - name: title
9 | content: Vue 3 Multiselect Component | The selecting solution for Vue 3
10 | - name: description
11 | content: Best-in-class multiselect component with Vue 3. Great DX with TypeScript, easy to use & easily customizable.
12 |
13 | hero:
14 | name: Vue 3 Multiselect Component
15 | text: The Selecting solution for Vue 3.
16 | tagline: Best-in-class multiselect component for Vue 3. Great DX, easy to use, and highly customizable.
17 | actions:
18 | - theme: brand
19 | text: Get Started
20 | link: /getting-started#multiselect-usage
21 | - theme: alt
22 | text: View on GitHub
23 | link: https://github.com/TotomInc/vue3-select-component
24 |
25 | features:
26 | - title: Best DX
27 | details: Built with TypeScript and Vue 3, the component provides a great developer experience with autocompletion and type checking.
28 | - title: Easy to Use
29 | details: The component leverage Vue's v-model to make it easy to use and integrate with your application.
30 | - title: Highly Customizable
31 | details: The component is highly customizable with a lot of options and slots to fit your needs.
32 | - title: Accessible
33 | details: The component is built with accessibility in mind and has been tested with screen readers.
34 | ---
35 |
--------------------------------------------------------------------------------
/docs/options.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Options'
3 | ---
4 |
5 | # Options
6 |
7 | The `options` prop is the core configuration for populating the dropdown menu. Understanding how to structure your options is essential for effective component usage.
8 |
9 | ## Basic structure
10 |
11 | Each option requires two key properties:
12 |
13 | ```vue
14 |
15 |
21 |
22 | ```
23 |
24 | **Properties:**
25 |
26 | - `label`: Text displayed in the dropdown menu
27 | - `value`: Data bound to `v-model` when the option is selected
28 |
29 | ::: info
30 | For TypeScript users, import the `Option` type to ensure proper type checking:
31 |
32 | ```ts
33 | import type { Option } from "vue3-select-component";
34 |
35 | const options: Option[] = [{ label: "JavaScript", value: "js" }];
36 | ```
37 | :::
38 |
39 | ## Disabling options
40 |
41 | Individual options can be disabled by adding the `disabled` property:
42 |
43 | ```vue
44 |
45 |
51 |
52 | ```
53 |
54 | Disabled options:
55 |
56 | - Cannot be selected
57 | - Cannot be focused with keyboard navigation
58 | - Have distinct visual styling
59 | - Include proper ARIA attributes for accessibility
60 |
61 | ## Extended Properties
62 |
63 | Options can include additional properties beyond the standard `label`/`value` pair:
64 |
65 | ```vue
66 |
67 |
78 |
79 | {{ option.label }} - Created by {{ option.creator }}
80 |
81 |
82 |
83 | ```
84 |
85 | ::: info
86 | When using extended properties with TypeScript, extend the `Option` type:
87 |
88 | ```ts
89 | type LanguageOption = Option & {
90 | version: string;
91 | creator: string;
92 | };
93 | ```
94 |
95 | For more details, see the [Extending option properties guide](./typescript.md#extending-option-properties).
96 | :::
97 |
--------------------------------------------------------------------------------
/docs/props.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Props'
3 | ---
4 |
5 | # Props
6 |
7 | ::: info
8 | This component is **ready to be used in production**. However, if there is a feature you would like to see implemented, feel free to open an issue or submit a pull request.
9 | :::
10 |
11 | ## v-model
12 |
13 | **Type**: `any | any[]`
14 |
15 | **Required**: `true`
16 |
17 | The value of the select. If `isMulti` is `true`, the `v-model` should be an array of any `any[]`.
18 |
19 | ::: info
20 | If using TypeScript, you can leverage proper type-safety between `option.value` & `v-model`. By doing this, you don't have an `any` type. Read more about [TypeScript usage](/typescript).
21 | :::
22 |
23 | ## options
24 |
25 | **Type**: `Option[]`
26 |
27 | **Required**: `true`
28 |
29 | A list of all possible options to choose from. Each option should have a `label` and a `value` property. You can add any other properties to the options, which will be passed to the `option` slot.
30 |
31 | **Type interface**:
32 |
33 | ```ts
34 | type Option = {
35 | label: string;
36 | value: T;
37 | disabled?: boolean;
38 | };
39 | ```
40 |
41 | ::: tip
42 | This type is exported from the component and can be imported in your application.
43 | :::
44 |
45 | ::: info
46 | If you are using TypeScript, you can leverage proper type-safety between `option.value` & `v-model`. Read more about [TypeScript usage](/typescript).
47 | :::
48 |
49 | ### option.disabled
50 |
51 | **Type**: `boolean`
52 |
53 | **Required**: `false`
54 |
55 | **Default**: `undefined`
56 |
57 | Whether the option should be disabled. When an option is disabled, it cannot be selected nor focused/navigated to using the keyboard. It also benefits from extra aria attributes to improve accessibility.
58 |
59 | ## displayedOptions
60 |
61 | **Type**: `Option[]`
62 |
63 | **Required**: `false`
64 |
65 | A list of specific options to display inside the option menu. This is useful when you want to create a complex filter logic inside the options menu.
66 |
67 | ::: warning
68 | When this prop is passed to the component, the `options` prop won't be used anymore for the rendering of the options menu.
69 |
70 | However, **it is still used internally to keep track of selected value(s)**.
71 |
72 | You should pass a list of all possible options to the `options` prop, and a list of specific options to display inside the option menu to the `displayedOptions` prop.
73 | :::
74 |
75 | For more details, see the [custom displayed options](/demo/custom-displayed-options) demo.
76 |
77 | ## placeholder
78 |
79 | **Type**: `string`
80 |
81 | **Default**: `Select an option`
82 |
83 | The placeholder text to show when no option is selected.
84 |
85 | ## isClearable
86 |
87 | **Type**: `boolean`
88 |
89 | **Default**: `true`
90 |
91 | Whether the select should have a clear button to reset the selected value.
92 |
93 | ## isDisabled
94 |
95 | **Type**: `boolean`
96 |
97 | **Default**: `false`
98 |
99 | Whether the select should be disabled.
100 |
101 | ## isSearchable
102 |
103 | **Type**: `boolean`
104 |
105 | **Default**: `true`
106 |
107 | Whether the select should have a search input to filter the options.
108 |
109 | ## isMulti
110 |
111 | **Type**: `boolean`
112 |
113 | **Default**: `false`
114 |
115 | Whether the select should allow multiple selections. If `true`, the `v-model` should be an array of string `string[]`.
116 |
117 | ## isTaggable
118 |
119 | **Type**: `boolean`
120 |
121 | **Default**: `false`
122 |
123 | Whether the select should allow creating a new option if it doesn't exist. When `true`, if the user searches for an option that isn't part of the list, the menu will display a text to ask if the user wants to create this option.
124 |
125 | ::: info
126 | It is up to the user to intercept the new option (using `@option-created` event) and manipulate its array of options provided with the `:options` prop. It is also recommended to slugify the value received and ensure it is unique.
127 | For more details, see the [Multiple Select Taggable](/demo/multiple-select-taggable) demo.
128 | :::
129 |
130 | ## isLoading
131 |
132 | **Type**: `boolean`
133 |
134 | **Default**: `false`
135 |
136 | Whether the select should display a loading state. When `true`, the select will show a loading spinner or custom loading content provided via the `loading` slot.
137 |
138 | ## isMenuOpen
139 |
140 | **Type**: `boolean`
141 |
142 | **Default**: `undefined`
143 |
144 | A prop to control the menu open state programmatically. When set to `true`, the menu will be open. When set to `false`, the menu will be closed.
145 |
146 | ## hideSelectedOptions
147 |
148 | **Type**: `boolean`
149 |
150 | **Default**: `true`
151 |
152 | When set to `true` with `isMulti`, selected options won't appear in the options menu. Set it to `false` to show selected options in the menu.
153 |
154 | ## shouldAutofocusOption
155 |
156 | **Type**: `boolean`
157 |
158 | **Default**: `true`
159 |
160 | Whether the first option should be focused when the dropdown is opened. If set to `false`, the first option will not be focused, and the user will have to navigate through the options using the keyboard.
161 |
162 | ## closeOnSelect
163 |
164 | **Type**: `boolean`
165 |
166 | **Default**: `true`
167 |
168 | Whether the dropdown should close after an option is selected.
169 |
170 | ## teleport
171 |
172 | **Type**: `string`
173 |
174 | **Default**: `undefined`
175 |
176 | Teleport the menu outside of the component DOM tree. You can pass a valid string according to the official Vue 3 Teleport documentation (e.g. `teleport="body"` will teleport the menu into the `` tree). This can be used in case you are having `z-index` issues within your DOM tree structure.
177 |
178 | ::: info
179 | Top and left properties are calculated using a ref on the `.vue-select` with a `container.getBoundingClientRect()`.
180 | :::
181 |
182 | ## inputId
183 |
184 | **Type**: `string`
185 |
186 | **Default**: `undefined`
187 |
188 | The `id` attribute to be passed to the `` element. This is useful for accessibility or forms.
189 |
190 | ## classes
191 |
192 | **Type**:
193 |
194 | ```ts
195 | type SelectClasses = {
196 | container?: string;
197 | control?: string;
198 | valueContainer?: string;
199 | placeholder?: string;
200 | singleValue?: string;
201 | multiValue?: string;
202 | multiValueLabel?: string;
203 | multiValueRemove?: string;
204 | inputContainer?: string;
205 | searchInput?: string;
206 | menuContainer?: string;
207 | menuOption?: string;
208 | noResults?: string;
209 | taggableNoOptions?: string;
210 | };
211 | ```
212 |
213 | **Default**: `undefined`
214 |
215 | CSS classes to be applied at multiple places in the select component. Useful when using TailwindCSS to customize the component.
216 |
217 | ## uid
218 |
219 | **Type**: `string | number`
220 |
221 | **Default**: `number`
222 |
223 | A unique identifier to be passed to the select control. Will be used on multiple `id` attributes for accessibility purposes such as `aria-owns`, `aria-controls`, etc.
224 |
225 | ## aria
226 |
227 | **Type**: `{ labelledby?: string; required?: boolean; }`
228 |
229 | **Default**: `undefined`
230 |
231 | Aria attributes to be passed to the select control to improve accessibility.
232 |
233 | ## disableInvalidVModelWarn
234 |
235 | **Type**: `boolean`
236 |
237 | **Default**: `false`
238 |
239 | When set to true, the component will not emit a `console.warn` because of an invalid `v-model` type when using `isMulti`. This is useful when using the component with dynamic `v-model` references.
240 |
241 | ## filterBy
242 |
243 | **Type**:
244 |
245 | ```ts
246 | (option: Option, label: string, search: string) => boolean;
247 | ```
248 |
249 | **Default**:
250 |
251 | ```ts
252 | (option, label, search) => label.toLowerCase().includes(search.toLowerCase());
253 | ```
254 |
255 | Callback function to determine if the current option should match the search query. This function is called for each option and should return a boolean.
256 |
257 | The `label` is provided as a convenience, processed from `getOptionLabel` prop.
258 |
259 | ::: info
260 | By default, the following callback function is used `(option, label, search) => label.toLowerCase().includes(search.toLowerCase())`
261 | :::
262 |
263 | ## getOptionLabel
264 |
265 | **Type**:
266 |
267 | ```ts
268 | (option: Option) => string;
269 | ```
270 |
271 | **Default**:
272 |
273 | ```ts
274 | (option) => option.label;
275 | ```
276 |
277 | Resolves option data to a string to render the option label.
278 |
279 | This function can be used if you don't want to use the standard `option.label` as the label of the option.
280 |
281 | The label of an option is displayed in the dropdown and as the selected option (**single-value**) in the select.
282 |
283 | ## getOptionValue
284 |
285 | **Type**:
286 |
287 | ```ts
288 | (option: Option) => string;
289 | ```
290 |
291 | **Default**:
292 |
293 | ```ts
294 | (option) => option.value;
295 | ```
296 |
297 | Resolves option data to a string to compare options and specify value attributes.
298 |
299 | This function can be used if you don't want to use the standard `option.value` as the value of the option.
300 |
--------------------------------------------------------------------------------
/docs/public/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TotomInc/vue3-select-component/cb800b4548514312bec16cc81e8621827b9758e8/docs/public/favicon.ico
--------------------------------------------------------------------------------
/docs/public/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TotomInc/vue3-select-component/cb800b4548514312bec16cc81e8621827b9758e8/docs/public/favicon.png
--------------------------------------------------------------------------------
/docs/public/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/TotomInc/vue3-select-component/cb800b4548514312bec16cc81e8621827b9758e8/docs/public/logo.png
--------------------------------------------------------------------------------
/docs/slots.md:
--------------------------------------------------------------------------------
1 | ---
2 | title: 'Slots'
3 | ---
4 |
5 | # Slots
6 |
7 | To ensure maximum flexibility, this component provides multiple ``s in order to allow for more customization.
8 |
9 | ::: info
10 | If you are not familiar with Vue's slots, you can read more about them [here](https://vuejs.org/guide/components/slots.html).
11 | :::
12 |
13 | ## option
14 |
15 | **Type**:
16 |
17 | ```ts
18 | slotProps: {
19 | option: Option;
20 | index: number;
21 | isFocused: boolean;
22 | isSelected: boolean;
23 | isDisabled: boolean;
24 | }
25 | ```
26 |
27 | Customize the rendered template of an option inside the menu. You can use the slot props to retrieve the current menu option that will be rendered in order to have more context and flexbility.
28 |
29 | ```vue
30 |
31 |
32 |
33 | {{ option.label }} - {{ option.value }} (#{{ index }})
34 |
35 |
36 |
37 | ```
38 |
39 | ## value
40 |
41 | **Type**: `slotProps: { option: Option }`
42 |
43 | Customize the rendered template if a selected option (inside the select control). You can use the slot props to retrieve the current selected option.
44 |
45 | ```vue
46 |
47 |
48 |
49 | My value is: {{ option.value }}
50 |
51 |
52 |
53 | ```
54 |
55 | ## tag
56 |
57 | **Type**: `slotProps: { option: Option, removeOption: () => void }`
58 |
59 | When using `isMulti` prop, customize the rendered template of a selected option. You can use the slot props to retrieve the current selected option and a function to remove it.
60 |
61 | ```vue
62 |
63 |
68 |
69 | {{ option.label }}
70 |
71 |
72 |
73 | ```
74 |
75 | ## menu-header
76 |
77 | **Type**: `slotProps: {}`
78 |
79 | Customize the rendered template for the menu header. This slot is placed **before** the options.
80 |
81 | ```vue
82 |
83 |
84 |
85 |
6 |
7 | 
20 |
21 |
22 |
23 | 
