feat(select): add classes prop (#244)

TotomInc · web-flow · commit 5c9b9cc76e17 · 2025-04-09T15:35:08.000+02:00
Fixes #241
diff --git a/docs/props.md b/docs/props.md
@@ -187,13 +187,32 @@ Top and left properties are calculated using a ref on the `.vue-select` with a `
 
 The `id` attribute to be passed to the `<input />` element. This is useful for accessibility or forms.
 
-## class
+## classes
 
-**Type**: `string`
+**Type**:
+
+```ts
+type SelectClasses = {
+  container?: string;
+  control?: string;
+  valueContainer?: string;
+  placeholder?: string;
+  singleValue?: string;
+  multiValue?: string;
+  multiValueLabel?: string;
+  multiValueRemove?: string;
+  inputContainer?: string;
+  searchInput?: string;
+  menuContainer?: string;
+  menuOption?: string;
+  noResults?: string;
+  taggableNoOptions?: string;
+};
+```
 
 **Default**: `undefined`
 
-A custom class to be passed to the select control.
+CSS classes to be applied at multiple places in the select component. Useful when using TailwindCSS to customize the component.
 
 ## uid
 
diff --git a/docs/styling.md b/docs/styling.md
@@ -123,6 +123,41 @@ You can also use the `:deep` selector to apply the CSS variables to the componen
 </style>
 ```
 
+## Custom classes with TailwindCSS
+
+The component provides a `classes` prop that allows you to apply custom TailwindCSS classes to different parts of the select component. This is particularly useful when you want to customize the appearance without overriding the default CSS variables.
+
+Here's an example of how to use TailwindCSS classes with the component:
+
+```vue
+<template>
+  <VueSelect
+    v-model="selected"
+    :options="options"
+    :classes="{
+      container: 'w-full max-w-md',
+      control: 'border-2 border-gray-200 hover:border-gray-300',
+      valueContainer: 'p-2',
+      placeholder: 'text-gray-400',
+      singleValue: 'text-gray-800 font-medium',
+      multiValue: 'bg-blue-100 rounded-md',
+      multiValueLabel: 'text-blue-800 px-2 py-1',
+      multiValueRemove: 'hover:bg-blue-200 px-2',
+      inputContainer: 'p-1',
+      searchInput: 'text-gray-700',
+      menuContainer: 'mt-1 border border-gray-200 rounded-md shadow-lg',
+      menuOption: 'px-3 py-2 hover:bg-gray-100',
+      noResults: 'text-gray-500 p-3',
+      taggableNoOptions: 'text-blue-600 p-3 hover:bg-blue-50',
+    }"
+  />
+</template>
+```
+
+::: warning
+When using TailwindCSS classes, be careful not to break the component's functionality by overriding essential styles like `display`, `position`, or `z-index` properties that are crucial for the component's layout and behavior.
+:::
+
 ## Scoped styling inside SFC
 
 You can apply any custom styling using [the `:deep` selector](https://vuejs.org/api/sfc-css-features.html#deep-selectors) inside a `<style scoped>`.
diff --git a/src/MultiValue.vue b/src/MultiValue.vue
@@ -1,8 +1,13 @@
 <script setup lang="ts">
 import XMarkIcon from "./icons/XMarkIcon.vue";
 
-defineProps<{
+const props = defineProps<{
   label: string;
+  classes?: {
+    multiValue?: string;
+    multiValueLabel?: string;
+    multiValueRemove?: string;
+  };
 }>();
 
 const emit = defineEmits<{
@@ -13,15 +18,17 @@ const emit = defineEmits<{
 <template>
   <div
     class="multi-value"
+    :class="props.classes?.multiValue"
   >
-    <div class="multi-value-label">
-      {{ label }}
+    <div class="multi-value-label" :class="props.classes?.multiValueLabel">
+      {{ props.label }}
     </div>
 
     <button
       type="button"
       class="multi-value-remove"
-      :aria-label="`Remove ${label}`"
+      :class="props.classes?.multiValueRemove"
+      :aria-label="`Remove ${props.label}`"
       @click.stop="emit('remove')"
     >
       <XMarkIcon />
diff --git a/src/Select.vue b/src/Select.vue
@@ -27,6 +27,7 @@ const props = withDefaults(
     closeOnSelect: true,
     teleport: undefined,
     inputId: undefined,
+    classes: undefined,
     uid: uniqueId(),
     aria: undefined,
     disableInvalidVModelWarn: false,
@@ -370,18 +371,18 @@ onBeforeUnmount(() => {
     ref="container"
     dir="auto"
     class="vue-select"
-    :class="[{ open: menuOpen, typing: menuOpen && search.length > 0, disabled: isDisabled }, props.class]"
+    :class="[{ open: menuOpen, typing: menuOpen && search.length > 0, disabled: isDisabled }, props.classes?.container]"
     :data-state="menuOpen ? 'open' : 'closed'"
   >
     <div
       class="control"
-      :class="{ focused: menuOpen, disabled: props.isDisabled }"
+      :class="[{ focused: menuOpen, disabled: props.isDisabled }, props.classes?.control]"
       @click="handleControlClick($event)"
     >
       <div
         :id="`vue-select-${uid}-combobox`"
         class="value-container"
-        :class="{ 'multi': isMulti, 'has-value': selectedOptions.length > 0 }"
+        :class="[{ 'multi': isMulti, 'has-value': selectedOptions.length > 0 }, props.classes?.valueContainer]"
         role="combobox"
         :aria-expanded="menuOpen"
         :aria-describedby="placeholder"
@@ -396,11 +397,13 @@ onBeforeUnmount(() => {
         <Placeholder
           v-if="!selectedOptions[0] && !search.length"
           :text="placeholder"
+          :class="props.classes?.placeholder"
         />
 
         <div
           v-else-if="!props.isMulti && selectedOptions[0]"
           class="single-value"
+          :class="[props.classes?.singleValue]"
           @click="openMenu()"
         >
           <slot name="value" :option="selectedOptions[0]">
@@ -418,20 +421,29 @@ onBeforeUnmount(() => {
             :option="selectedOption"
             :remove-option="() => removeOption(selectedOption)"
           >
-            <MultiValue :label="getOptionLabel(selectedOption)" @remove="removeOption(selectedOption)" />
+            <MultiValue
+              :label="getOptionLabel(selectedOption)"
+              :classes="{
+                multiValue: props.classes?.multiValue,
+                multiValueLabel: props.classes?.multiValueLabel,
+                multiValueRemove: props.classes?.multiValueRemove,
+              }"
+              @remove="removeOption(selectedOption)"
+            />
           </slot>
         </template>
 
         <div
           class="input-container"
-          :class="{ typing: menuOpen && search.length > 0 }"
+          :class="[{ typing: menuOpen && search.length > 0 }, props.classes?.inputContainer]"
           :data-value="search"
         >
           <input
             :id="inputId"
             ref="input"
             v-model="search"
             class="search-input"
+            :class="props.classes?.searchInput"
             autocapitalize="none"
             autocomplete="off"
             autocorrect="off"
@@ -488,6 +500,7 @@ onBeforeUnmount(() => {
         :id="`vue-select-${uid}-listbox`"
         ref="menu"
         class="menu"
+        :class="props.classes?.menuContainer"
         role="listbox"
         :aria-label="aria?.labelledby"
         :aria-multiselectable="isMulti"
@@ -508,6 +521,7 @@ onBeforeUnmount(() => {
           :is-focused="focusedOption === i"
           :is-selected="Array.isArray(selected) ? selected.includes(option.value) : option.value === selected"
           :is-disabled="option.disabled || false"
+          :class="props.classes?.menuOption"
           @select="setOption(option)"
         >
           <slot
@@ -522,7 +536,11 @@ onBeforeUnmount(() => {
           </slot>
         </MenuOption>
 
-        <div v-if="!isTaggable && availableOptions.length === 0" class="no-results">
+        <div
+          v-if="!isTaggable && availableOptions.length === 0"
+          class="no-results"
+          :class="props.classes?.noResults"
+        >
           <slot name="no-options">
             No results found
           </slot>
@@ -531,6 +549,7 @@ onBeforeUnmount(() => {
         <div
           v-if="isTaggable && search"
           class="taggable-no-options"
+          :class="props.classes?.taggableNoOptions"
           @click="createOption"
         >
           <slot
diff --git a/src/types.ts b/src/types.ts
@@ -5,6 +5,23 @@ export type Option<T> = {
   [key: string]: unknown;
 };
 
+export type SelectClasses = {
+  container?: string;
+  control?: string;
+  valueContainer?: string;
+  placeholder?: string;
+  singleValue?: string;
+  multiValue?: string;
+  multiValueLabel?: string;
+  multiValueRemove?: string;
+  inputContainer?: string;
+  searchInput?: string;
+  menuContainer?: string;
+  menuOption?: string;
+  noResults?: string;
+  taggableNoOptions?: string;
+};
+
 export type Props<GenericOption, OptionValue> = {
   /**
    * A list of options to render on the select component.
@@ -90,9 +107,9 @@ export type Props<GenericOption, OptionValue> = {
   inputId?: string;
 
   /**
-   * CSS class to append to the select component at the root level.
+   * CSS classes to apply to the select component.
    */
-  class?: string;
+  classes?: SelectClasses;
 
   /**
    * Unique identifier to identify the select component, using `id` attribute.
