From 730bc3a7752874455e481544d2a949bdd9d8266d Mon Sep 17 00:00:00 2001
From: alectimison-maker <alec.timison@gmail.com>
Date: Wed, 5 Aug 2026 07:53:15 +0800
Subject: [PATCH] docs: explain Tailwind styling in v1

---
 docs/content/2.guide/4.styling.md   | 90 +++++++++++++++++++++++++++++
 docs/content/2.guide/7.migration.md |  8 +++
 2 files changed, 98 insertions(+)

diff --git a/docs/content/2.guide/4.styling.md b/docs/content/2.guide/4.styling.md
index faf6905f..c38b9a75 100644
--- a/docs/content/2.guide/4.styling.md
+++ b/docs/content/2.guide/4.styling.md
@@ -108,6 +108,96 @@ Because the popover teleports to `document.body`, set popover-specific variables
 
 See [`src/styles.css`](https://github.com/TotomInc/vue3-select-component/blob/v1-dev/src/styles.css) for the full list.
 
+## Tailwind CSS
+
+v1 does not include the v0 `classes` prop. For small changes to the assembled
+`Select`, add a class to the component and use Tailwind's arbitrary variants to
+target its stable data attributes:
+
+```vue [App.vue]
+<script setup lang="ts">
+import { ref } from "vue"
+import Select from "vue3-select-component"
+
+const value = ref<string | null>(null)
+const options = [
+  { label: "Option #1", value: "option_1" },
+  { label: "Option #2", value: "option_2" },
+]
+</script>
+
+<template>
+  <Select
+    v-model="value"
+    :options="options"
+    class="[&_[data-select-trigger]]:rounded-xl [&_[data-select-trigger]]:border-sky-500"
+  />
+</template>
+```
+
+The popover is teleported to `document.body` by default, so descendant variants
+on the assembled root cannot reach it. Target the global data hook from your CSS
+instead:
+
+```css [app.css]
+@layer components {
+  [data-select-popover] {
+    @apply rounded-xl border-sky-500 shadow-lg;
+  }
+
+  [data-select-option][data-active="true"] {
+    @apply bg-sky-100;
+  }
+}
+```
+
+When every element needs utility classes, compose the unstyled primitives and
+put classes directly on them:
+
+```vue [App.vue]
+<script setup lang="ts">
+import { ref } from "vue"
+import {
+  SelectInput,
+  SelectListbox,
+  SelectOption,
+  SelectPopover,
+  SelectRoot,
+  SelectTrigger,
+  SelectValue,
+} from "vue3-select-component/primitives"
+
+const value = ref<string | null>(null)
+const options = [
+  { label: "Option #1", value: "option_1" },
+  { label: "Option #2", value: "option_2" },
+]
+</script>
+
+<template>
+  <SelectRoot v-model="value" :options="options">
+    <SelectTrigger class="flex w-full rounded-xl border border-sky-500 px-3 py-2">
+      <SelectValue />
+      <SelectInput />
+    </SelectTrigger>
+
+    <SelectPopover class="mt-2 rounded-xl border bg-white shadow-lg">
+      <SelectListbox>
+        <SelectOption
+          v-for="option in options"
+          :key="option.value"
+          :value="option.value"
+          :label="option.label"
+          class="cursor-pointer px-3 py-2 data-[active=true]:bg-sky-100"
+        />
+      </SelectListbox>
+    </SelectPopover>
+  </SelectRoot>
+</template>
+```
+
+Skip the default stylesheet when you want a fully Tailwind-owned design.
+
 ## Headless styling with data attributes
 
 Every primitive exposes stable `data-*` hooks for custom CSS:
diff --git a/docs/content/2.guide/7.migration.md b/docs/content/2.guide/7.migration.md
index 2576f810..cec97271 100644
--- a/docs/content/2.guide/7.migration.md
+++ b/docs/content/2.guide/7.migration.md
@@ -66,6 +66,14 @@ Keep `import "vue3-select-component/styles"` for the assembled `Select`. Default
 
 For custom primitive compositions, skip the stylesheet and style via `data-*` selectors. See [Styling](/guide/styling).
 
+### Replace the `classes` prop
+
+The v0 `classes` prop was removed in v1. For Tailwind or another utility CSS
+framework, use arbitrary variants with the assembled `Select`'s stable `data-*`
+hooks, or compose the unstyled primitives and apply classes directly to each
+element. The [Tailwind CSS guide](/guide/styling#tailwind-css) shows both
+approaches and explains how to style the teleported popover.
+
 ## Map slots to primitives
 
 v0 slots on the monolithic component map to primitive slots: