feat(select): add isTaggable prop

* feat: add tagging to create an option when it doesn't exist

Fixes #119

* feat(select): improve props docs

* fix(select): update isTaggable implementation

* feat(playground): add isTaggable demo

* feat(docs): add multiple select taggable (:isTaggable) demo

* feat(select): expose createOption for taggable-no-options slot

* fix(select): menu-option white-space

* feat(playground): rewrite playground with multiple demos

* chore: run linter

* feat(playground): add more playground demos

* fix(select): remove createOption, add onClick on isTaggable div

* fix: update tests

Author: TotomInc

README.md

@@ -82,8 +82,9 @@ It also leverages the power of generics to provide types for additional properti
 
 ```vue
 <script setup lang="ts">
+import type { Option } from "vue3-select-component";
 import { ref } from "vue";
-import VueSelect, { type Option } from "vue3-select-component";
+import VueSelect from "vue3-select-component";
 
 type UserOption = Option<number> & { username: string };
 

docs/.vitepress/config.ts

@@ -46,6 +46,7 @@ export default defineConfig({
         items: [
           { text: "Single select", link: "/demo/single-select" },
           { text: "Multiple Select", link: "/demo/multiple-select" },
+          { text: "Multiple Select Taggable", link: "/demo/multiple-select-taggable" },
           { text: "Custom option slot", link: "/demo/custom-option-slot" },
           { text: "Custom tag slot", link: "/demo/custom-tag-slot" },
           { text: "Custom value/label properties", link: "/demo/custom-option-label-value" },

docs/demo/multiple-select-taggable.md

@@ -0,0 +1,76 @@
+---
+title: 'Multiple Select Taggable'
+---
+
+# Multiple Select Taggable
+
+The following example demonstrates how to use the `VueSelect` component to create a multiple select dropdown with taggable options _(options that are created by the user)_.
+
+::: warning
+Setting `is-multi` to `true` will change the `v-model` to become an array of any `any[]`. Make sure to update your `v-model` accordingly.
+:::
+
+<script setup>
+import { ref } from "vue";
+
+import VueSelect from "../../src";
+
+const selected = ref([]);
+
+const options = ref([
+  { label: "JavaScript", value: "javascript" },
+  { label: "TypeScript", value: "typescript" },
+  { label: "Swift", value: "swift" },
+  { label: "Kotlin", value: "kotlin" },
+]);
+
+const handleCreateOption = (value) => {
+  options.value.push({ label: value, value });
+  selected.value.push(value);
+};
+</script>
+
+<VueSelect
+  v-model="selected"
+  :is-multi="true"
+  :is-taggable="true"
+  :options="options"
+  @option-created="(value) => handleCreateOption(value)"
+/>
+
+Selected value(s): **{{ selected.length ? selected.join(", ") : "none" }}**
+
+## Demo source-code
+
+```vue
+<script setup lang="ts">
+import type { Option } from "vue3-select-component";
+import { ref } from "vue";
+import VueSelect from "vue3-select-component";
+
+// When setting `is-multi` to `true`, the `v-model` should be an array of strings.
+const selected = ref<string[]>([]);
+
+const options = ref<Option<string>>([
+  { label: "JavaScript", value: "javascript" },
+  { label: "TypeScript", value: "typescript" },
+  { label: "Swift", value: "swift" },
+  { label: "Kotlin", value: "kotlin" },
+]);
+
+const handleCreateOption = (value) => {
+  options.value.push({ label: value, value });
+  selected.value.push(value);
+};
+</script>
+
+<template>
+  <VueSelect
+    v-model="selected"
+    :is-multi="true"
+    :is-taggable="true"
+    :options="options"
+    @option-created="(value) => handleCreateOption(value)"
+  />
+</template>
+```

docs/props.md

@@ -114,6 +114,19 @@ Whether the select should have a search input to filter the options.
 
 Whether the select should allow multiple selections. If `true`, the `v-model` should be an array of string `string[]`.
 
+## isTaggable
+
+**Type**: `boolean`
+
+**Default**: `false`
+
+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.
+
+::: info
+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.
+For more details, see the [Multiple Select Taggable](/demo/multiple-select-taggable) demo.
+:::
+
 ## isLoading
 
 **Type**: `boolean`
@@ -122,6 +135,14 @@ Whether the select should allow multiple selections. If `true`, the `v-model` sh
 
 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.
 
+## isMenuOpen
+
+**Type**: `boolean`
+
+**Default**: `undefined`
+
+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.
+
 ## shouldAutofocusOption
 
 **Type**: `boolean`
@@ -226,10 +247,21 @@ Resolves option data to a string to compare options and specify value attributes
 
 This function can be used if you don't want to use the standard `option.value` as the value of the option.
 
-## isMenuOpen
+## Events
 
-**Type**: `boolean`
+### option-created
 
-**Default**: `undefined`
+Emitted when a new option is created with the `:taggable="true"` prop.
 
-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.
+**Payload**: `string` - The search content value.
+
+```vue
+<template>
+  <VueSelect
+    v-model="selectedValue"
+    :options="options"
+    :taggable="true"
+    @option-created="(value) => console.log('New option created:', value)"
+  />
+</template>
+```

docs/slots.md

@@ -147,3 +147,23 @@ Customize the rendered template when the select component is in a loading state.
   </VueSelect>
 </template>
 ```
+
+## taggable-no-options
+
+**Type**: `slotProps: { option: string }`
+
+Customize the rendered template when there are no matching options and the `taggable` prop is set to `true`. You can use the slot props to retrieve the current search value.
+
+```vue
+<template>
+  <VueSelect
+    v-model="option"
+    :options="options"
+    :taggable="true"
+  >
+    <template #taggable-no-options="{ option }">
+      Press enter to add {{ option }} option
+    </template>
+  </VueSelect>
+</template>
+```

package-lock.json

@@ -66,6 +66,7 @@
     "vitepress": "1.6.3",
     "vitest": "3.0.5",
     "vue": "3.5.13",
+    "vue-router": "4.5.0",
     "vue-tsc": "2.2.0"
   }
 }