feat(slots): 281 placeholder slot

nats-afs · TotomInc · commit 21fe3dbe121a · 2025-07-18T10:01:48.000+02:00
diff --git a/docs/slots.md b/docs/slots.md
@@ -177,3 +177,19 @@ Customize the rendered template when there are no matching options and the `tagg
   </VueSelect>
 </template>
 ```
+
+## placeholder
+
+**Type**: `slotProps: { text: string }`
+
+Customize the rendered template for the placeholder.
+
+```vue
+<template>
+  <VueSelect v-model="option" :options="options">
+    <template #placeholder>
+      <span>Custom placeholder</span>
+    </template>
+  </VueSelect>
+</template>
+```
diff --git a/playground/PlaygroundLayout.vue b/playground/PlaygroundLayout.vue
@@ -8,6 +8,7 @@ const links = [
   { value: "/single-select", label: "Single Select" },
   { value: "/multi-select", label: "Multi Select" },
   { value: "/multi-select-taggable", label: "Multi Select Taggable" },
+  { value: "/custom-placeholder", label: "Custom Placeholder" },
   { value: "/extra-option-properties", label: "Extra Option Properties" },
   { value: "/custom-option-label-value", label: "Custom Option Label/Value" },
   { value: "/custom-search-filter", label: "Custom Search Filter" },
diff --git a/playground/demos/CustomPlaceholder.vue b/playground/demos/CustomPlaceholder.vue
@@ -0,0 +1,30 @@
+<script setup lang="ts">
+import type { Option } from "../../src";
+import { ref } from "vue";
+import VueSelect from "../../src";
+
+const selected = ref<string | null>(null);
+const options: Option<string>[] = [
+  { label: "Alice's Adventures in Wonderland", value: "alice" },
+  { label: "A Wizard of Earthsea", value: "wizard" },
+  { label: "Harry Potter and the Philosopher's Stone", value: "harry_potter_1" },
+  { label: "Harry Potter and the Chamber of Secrets", value: "harry_potter_2" },
+];
+</script>
+
+<template>
+  <VueSelect
+    v-model="selected"
+    :options="options"
+    :is-multi="false"
+    placeholder="Pick a book"
+  >
+    <template #placeholder>
+      <span>Custom placeholder</span>
+    </template>
+  </VueSelect>
+
+  <p class="selected-value">
+    Selected book value: {{ selected || "none" }}
+  </p>
+</template>
diff --git a/playground/main.ts b/playground/main.ts
@@ -3,6 +3,7 @@ import { createRouter, createWebHistory } from "vue-router";
 
 import ControlledMenu from "./demos/ControlledMenu.vue";
 import CustomOptionLabelValue from "./demos/CustomOptionLabelValue.vue";
+import CustomPlaceholder from "./demos/CustomPlaceholder.vue";
 import CustomSearchFilter from "./demos/CustomSearchFilter.vue";
 import ExtraOptionProperties from "./demos/ExtraOptionProperties.vue";
 import MenuHeader from "./demos/MenuHeader.vue";
@@ -20,6 +21,7 @@ const router = createRouter({
     { path: "/single-select", component: SingleSelect },
     { path: "/multi-select", component: MultiSelect },
     { path: "/multi-select-taggable", component: MultiSelectTaggable },
+    { path: "/custom-placeholder", component: CustomPlaceholder },
     { path: "/extra-option-properties", component: ExtraOptionProperties },
     { path: "/custom-option-label-value", component: CustomOptionLabelValue },
     { path: "/custom-search-filter", component: CustomSearchFilter },
diff --git a/src/Placeholder.vue b/src/Placeholder.vue
@@ -1,12 +1,20 @@
-<script setup lang="ts">
+<script setup lang="ts" generic="GenericOption extends Option<OptionValue>, OptionValue = string">
+import type { Option } from "./types/option";
+import type { Slots } from "./types/slots";
+
 defineProps<{
   text: string;
+  placeholderSlot?: Slots<GenericOption, OptionValue>["placeholder"];
 }>();
 </script>
 
 <template>
   <div class="input-placeholder">
-    {{ text }}
+    <component :is="placeholderSlot" v-if="placeholderSlot" />
+
+    <template v-else>
+      {{ text }}
+    </template>
   </div>
 </template>
 
diff --git a/src/Select.spec.ts b/src/Select.spec.ts
@@ -1,7 +1,8 @@
 import type { Option } from "./types/option";
 import { mount } from "@vue/test-utils";
-
 import { describe, expect, it } from "vitest";
+import { h } from "vue";
+
 import VueSelect from "./Select.vue";
 
 const options = [
@@ -40,6 +41,18 @@ describe("input + menu interactions behavior", () => {
     expect(wrapper.find(".input-placeholder").text()).toBe("Select an option");
   });
 
+  it("should display the placeholder slot", async () => {
+    const wrapper = mount(VueSelect, {
+      props: { modelValue: null, options, placeholder: "placeholder prop" },
+      slots: {
+        placeholder: () => h("div", { class: "custom-placeholder" }, "Custom placeholder"),
+      },
+    });
+
+    expect(wrapper.find(".custom-placeholder").exists()).toBe(true);
+    expect(wrapper.get(".custom-placeholder").text()).toBe("Custom placeholder");
+  });
+
   it("should not open the menu when focusing the input", async () => {
     const wrapper = mount(VueSelect, { props: { modelValue: null, options } });
 
diff --git a/src/Select.vue b/src/Select.vue
@@ -314,11 +314,13 @@ watch(
         :aria-controls="`vue-select-${uid}-listbox`"
         aria-haspopup="true"
       >
-        <Placeholder
-          v-if="!selectedOptions[0] && !search.length"
-          :text="placeholder"
-          :class="props.classes?.placeholder"
-        />
+        <template v-if="!selectedOptions[0] && !search.length">
+          <Placeholder
+            :text="placeholder"
+            :placeholder-slot="slots.placeholder"
+            :class="props.classes?.placeholder"
+          />
+        </template>
 
         <div
           v-else-if="!props.isMulti && selectedOptions[0]"
diff --git a/src/types/slots.ts b/src/types/slots.ts
@@ -15,6 +15,7 @@ export type Slots<GenericOption extends Option<OptionValue>, OptionValue> = {
   "option"?: (props: { option: GenericOption; index: number; isFocused: boolean; isSelected: boolean; isDisabled: boolean }) => any;
   "no-options"?: () => any;
   "taggable-no-options"?: () => any;
+  "placeholder"?: () => any;
 };
 
 export type IndicatorsSlots<GenericOption extends Option<OptionValue>, OptionValue> = Pick<
