From fb8e6a6a668a2d9a7950362641938416c91de772 Mon Sep 17 00:00:00 2001
From: Benjamin Canac <canacb1@gmail.com>
Date: Wed, 25 Sep 2024 19:07:21 +0200
Subject: [PATCH] docs(select-menu): update

---
 .../CommandPaletteFetchExample.vue            |   2 +-
 .../CommandPaletteFilterExample.vue           |   2 +-
 .../CommandPaletteFuseExample.vue             |   2 +-
 .../drawer/DrawerCommandPaletteExample.vue    |   2 +-
 .../modal/ModalCommandPaletteExample.vue      |   2 +-
 .../select-menu/SelectMenuFetchExample.vue    |  31 +
 .../select-menu/SelectMenuFilterExample.vue   |  37 +
 .../SelectMenuFilterFieldsExample.vue         |  41 ++
 .../select-menu/SelectMenuIconExample.vue     |  14 +
 .../SelectMenuItemsAvatarExample.vue          |  42 ++
 .../SelectMenuItemsChipExample.vue            |  41 ++
 .../SelectMenuItemsIconExample.vue            |  29 +
 .../select-menu/SelectMenuOpenExample.vue     |  13 +
 .../SelectMenuSearchTermExample.vue           |   9 +
 .../examples/select/SelectFetchExample.vue    |   2 +-
 docs/content/3.components/button.md           |   1 -
 docs/content/3.components/input.md            |   1 -
 docs/content/3.components/radio-group.md      |   4 +-
 docs/content/3.components/select-menu.md      | 635 +++++++++++++++++-
 docs/content/3.components/select.md           | 266 +++++---
 docs/nuxt.config.ts                           |   1 +
 21 files changed, 1054 insertions(+), 123 deletions(-)
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuFetchExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuFilterExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuFilterFieldsExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuIconExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuItemsAvatarExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuItemsChipExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuItemsIconExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuOpenExample.vue
 create mode 100644 docs/app/components/content/examples/select-menu/SelectMenuSearchTermExample.vue

diff --git a/docs/app/components/content/examples/command-palette/CommandPaletteFetchExample.vue b/docs/app/components/content/examples/command-palette/CommandPaletteFetchExample.vue
index ddd198da..d14a1a820 100644
--- a/docs/app/components/content/examples/command-palette/CommandPaletteFetchExample.vue
+++ b/docs/app/components/content/examples/command-palette/CommandPaletteFetchExample.vue
@@ -2,7 +2,7 @@
 const searchTerm = ref('')
 
 const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
-  transform: (data: any[]) => {
+  transform: (data: { id: number, name: string, email: string }[]) => {
     return data?.map(user => ({ id: user.id, label: user.name, suffix: user.email, avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` } })) || []
   },
   lazy: true
diff --git a/docs/app/components/content/examples/command-palette/CommandPaletteFilterExample.vue b/docs/app/components/content/examples/command-palette/CommandPaletteFilterExample.vue
index 9caf25f5..c237f0c1 100644
--- a/docs/app/components/content/examples/command-palette/CommandPaletteFilterExample.vue
+++ b/docs/app/components/content/examples/command-palette/CommandPaletteFilterExample.vue
@@ -4,7 +4,7 @@ const searchTermDebounced = refDebounced(searchTerm, 200)
 
 const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
   params: { q: searchTermDebounced },
-  transform: (data: any[]) => {
+  transform: (data: { id: number, name: string, email: string }[]) => {
     return data?.map(user => ({ id: user.id, label: user.name, suffix: user.email, avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` } })) || []
   },
   lazy: true
diff --git a/docs/app/components/content/examples/command-palette/CommandPaletteFuseExample.vue b/docs/app/components/content/examples/command-palette/CommandPaletteFuseExample.vue
index bb86f9de..c0415527 100644
--- a/docs/app/components/content/examples/command-palette/CommandPaletteFuseExample.vue
+++ b/docs/app/components/content/examples/command-palette/CommandPaletteFuseExample.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 const { data: users } = await useFetch('https://jsonplaceholder.typicode.com/users', {
-  transform: (data: any[]) => {
+  transform: (data: { id: number, name: string, email: string }[]) => {
     return data?.map(user => ({ id: user.id, label: user.name, suffix: user.email, avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` } })) || []
   },
   lazy: true
diff --git a/docs/app/components/content/examples/drawer/DrawerCommandPaletteExample.vue b/docs/app/components/content/examples/drawer/DrawerCommandPaletteExample.vue
index 7490e66d..72a8604e 100644
--- a/docs/app/components/content/examples/drawer/DrawerCommandPaletteExample.vue
+++ b/docs/app/components/content/examples/drawer/DrawerCommandPaletteExample.vue
@@ -3,7 +3,7 @@ const searchTerm = ref('')
 
 const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
   params: { q: searchTerm },
-  transform: (data: any[]) => {
+  transform: (data: { id: number, name: string, email: string }[]) => {
     return data?.map(user => ({ id: user.id, label: user.name, suffix: user.email, avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` } })) || []
   },
   lazy: true
diff --git a/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue b/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
index b32b5940..69d46971 100644
--- a/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
+++ b/docs/app/components/content/examples/modal/ModalCommandPaletteExample.vue
@@ -3,7 +3,7 @@ const searchTerm = ref('')
 
 const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
   params: { q: searchTerm },
-  transform: (data: any[]) => {
+  transform: (data: { id: number, name: string, email: string }[]) => {
     return data?.map(user => ({ id: user.id, label: user.name, suffix: user.email, avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` } })) || []
   },
   lazy: true
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuFetchExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuFetchExample.vue
new file mode 100644
index 00000000..3e43b3fb
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuFetchExample.vue
@@ -0,0 +1,31 @@
+<script setup lang="ts">
+const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
+  transform: (data: { id: number, name: string }[]) => {
+    return data?.map(user => ({
+      label: user.name,
+      value: String(user.id),
+      avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` }
+    })) || []
+  },
+  lazy: true
+})
+</script>
+
+<template>
+  <USelectMenu
+    :items="users || []"
+    :loading="status === 'pending'"
+    icon="i-heroicons-user"
+    placeholder="Select user"
+    class="w-48"
+  >
+    <template #leading="{ modelValue, ui }">
+      <UAvatar
+        v-if="modelValue"
+        v-bind="modelValue.avatar"
+        :size="ui.itemLeadingAvatarSize()"
+        :class="ui.itemLeadingAvatar()"
+      />
+    </template>
+  </USelectMenu>
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuFilterExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuFilterExample.vue
new file mode 100644
index 00000000..392a4184
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuFilterExample.vue
@@ -0,0 +1,37 @@
+<script setup lang="ts">
+const searchTerm = ref('')
+const searchTermDebounced = refDebounced(searchTerm, 200)
+
+const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
+  params: { q: searchTermDebounced },
+  transform: (data: { id: number, name: string }[]) => {
+    return data?.map(user => ({
+      label: user.name,
+      value: String(user.id),
+      avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` }
+    })) || []
+  },
+  lazy: true
+})
+</script>
+
+<template>
+  <USelectMenu
+    v-model:search-term="searchTerm"
+    :items="users || []"
+    :loading="status === 'pending'"
+    :filter="false"
+    icon="i-heroicons-user"
+    placeholder="Select user"
+    class="w-48"
+  >
+    <template #leading="{ modelValue, ui }">
+      <UAvatar
+        v-if="modelValue"
+        v-bind="modelValue.avatar"
+        :size="ui.itemLeadingAvatarSize()"
+        :class="ui.itemLeadingAvatar()"
+      />
+    </template>
+  </USelectMenu>
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuFilterFieldsExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuFilterFieldsExample.vue
new file mode 100644
index 00000000..94ef4ec6
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuFilterFieldsExample.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
+  transform: (data: { id: number, name: string, email: string }[]) => {
+    return data?.map(user => ({
+      label: user.name,
+      email: user.email,
+      value: String(user.id),
+      avatar: { src: `https://i.pravatar.cc/120?img=${user.id}` }
+    })) || []
+  },
+  lazy: true
+})
+</script>
+
+<template>
+  <USelectMenu
+    :items="users || []"
+    :loading="status === 'pending'"
+    :filter="['name', 'email']"
+    icon="i-heroicons-user"
+    placeholder="Select user"
+    class="w-80"
+  >
+    <template #leading="{ modelValue, ui }">
+      <UAvatar
+        v-if="modelValue"
+        v-bind="modelValue.avatar"
+        :size="ui.itemLeadingAvatarSize()"
+        :class="ui.itemLeadingAvatar()"
+      />
+    </template>
+
+    <template #item-label="{ item }">
+      {{ item.label }}
+
+      <span class="text-gray-500 dark:text-gray-400">
+        {{ item.email }}
+      </span>
+    </template>
+  </USelectMenu>
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuIconExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuIconExample.vue
new file mode 100644
index 00000000..37ff1295
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuIconExample.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
+const selected = ref('Backlog')
+</script>
+
+<template>
+  <USelectMenu
+    v-model="selected"
+    :items="items"
+    :ui="{
+      trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200'
+    }"
+  />
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuItemsAvatarExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuItemsAvatarExample.vue
new file mode 100644
index 00000000..15316554
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuItemsAvatarExample.vue
@@ -0,0 +1,42 @@
+<script setup lang="ts">
+const items = ref([
+  {
+    label: 'benjamincanac',
+    value: 'benjamincanac',
+    avatar: {
+      src: 'https://github.com/benjamincanac.png',
+      alt: 'benjamincanac'
+    }
+  },
+  {
+    label: 'romhml',
+    value: 'romhml',
+    avatar: {
+      src: 'https://github.com/romhml.png',
+      alt: 'romhml'
+    }
+  },
+  {
+    label: 'noook',
+    value: 'noook',
+    avatar: {
+      src: 'https://github.com/noook.png',
+      alt: 'noook'
+    }
+  }
+])
+const selected = ref(items.value[0])
+</script>
+
+<template>
+  <USelectMenu v-model="selected" :items="items" class="w-40">
+    <template #leading="{ modelValue, ui }">
+      <UAvatar
+        v-if="modelValue"
+        v-bind="modelValue.avatar"
+        :size="ui.itemLeadingAvatarSize()"
+        :class="ui.itemLeadingAvatar()"
+      />
+    </template>
+  </USelectMenu>
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuItemsChipExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuItemsChipExample.vue
new file mode 100644
index 00000000..32abd852
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuItemsChipExample.vue
@@ -0,0 +1,41 @@
+<script setup lang="ts">
+const items = ref([
+  {
+    label: 'bug',
+    value: 'bug',
+    chip: {
+      color: 'red' as const
+    }
+  },
+  {
+    label: 'enhancement',
+    value: 'enhancement',
+    chip: {
+      color: 'blue' as const
+    }
+  },
+  {
+    label: 'feature',
+    value: 'feature',
+    chip: {
+      color: 'violet' as const
+    }
+  }
+])
+const selected = ref(items.value[0])
+</script>
+
+<template>
+  <USelectMenu v-model="selected" :items="items" class="w-40">
+    <template #leading="{ modelValue, ui }">
+      <UChip
+        v-if="modelValue"
+        v-bind="modelValue.chip"
+        inset
+        standalone
+        :size="ui.itemLeadingChipSize()"
+        :class="ui.itemLeadingChip()"
+      />
+    </template>
+  </USelectMenu>
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuItemsIconExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuItemsIconExample.vue
new file mode 100644
index 00000000..b001cacf
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuItemsIconExample.vue
@@ -0,0 +1,29 @@
+<script setup lang="ts">
+const items = ref([
+  {
+    label: 'Backlog',
+    value: 'backlog',
+    icon: 'i-heroicons-question-mark-circle'
+  },
+  {
+    label: 'Todo',
+    value: 'todo',
+    icon: 'i-heroicons-plus-circle'
+  },
+  {
+    label: 'In Progress',
+    value: 'in_progress',
+    icon: 'i-heroicons-arrow-up-circle'
+  },
+  {
+    label: 'Done',
+    value: 'done',
+    icon: 'i-heroicons-check-circle'
+  }
+])
+const selected = ref(items.value[0])
+</script>
+
+<template>
+  <USelectMenu v-model="selected" :icon="selected?.icon" :items="items" class="w-40" />
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuOpenExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuOpenExample.vue
new file mode 100644
index 00000000..6c46f881
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuOpenExample.vue
@@ -0,0 +1,13 @@
+<script setup lang="ts">
+const open = ref(false)
+const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
+const selected = ref('Backlog')
+
+defineShortcuts({
+  o: () => open.value = !open.value
+})
+</script>
+
+<template>
+  <USelectMenu v-model="selected" v-model:open="open" :items="items" />
+</template>
diff --git a/docs/app/components/content/examples/select-menu/SelectMenuSearchTermExample.vue b/docs/app/components/content/examples/select-menu/SelectMenuSearchTermExample.vue
new file mode 100644
index 00000000..0a374775
--- /dev/null
+++ b/docs/app/components/content/examples/select-menu/SelectMenuSearchTermExample.vue
@@ -0,0 +1,9 @@
+<script setup lang="ts">
+const searchTerm = ref('D')
+const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
+const selected = ref('Backlog')
+</script>
+
+<template>
+  <USelectMenu v-model="selected" v-model:search-term="searchTerm" :items="items" />
+</template>
diff --git a/docs/app/components/content/examples/select/SelectFetchExample.vue b/docs/app/components/content/examples/select/SelectFetchExample.vue
index 140f738b..392be792 100644
--- a/docs/app/components/content/examples/select/SelectFetchExample.vue
+++ b/docs/app/components/content/examples/select/SelectFetchExample.vue
@@ -1,6 +1,6 @@
 <script setup lang="ts">
 const { data: users, status } = await useFetch('https://jsonplaceholder.typicode.com/users', {
-  transform: (data: { name: string, id: number }[]) => {
+  transform: (data: { id: number, name: string }[]) => {
     return data?.map(user => ({
       label: user.name,
       value: String(user.id),
diff --git a/docs/content/3.components/button.md b/docs/content/3.components/button.md
index 96f30bb0..7b0acc25 100644
--- a/docs/content/3.components/button.md
+++ b/docs/content/3.components/button.md
@@ -157,7 +157,6 @@ Use the `loading-icon` prop to customize the loading icon. Defaults to `i-heroic
 props:
   loading: true
   loadingIcon: 'i-heroicons-arrow-path-rounded-square'
-  trailing: false
 slots:
   default: Button
 ---
diff --git a/docs/content/3.components/input.md b/docs/content/3.components/input.md
index b394b220..8d9d0f61 100644
--- a/docs/content/3.components/input.md
+++ b/docs/content/3.components/input.md
@@ -162,7 +162,6 @@ ignore:
 props:
   loading: true
   loadingIcon: 'i-heroicons-arrow-path-rounded-square'
-  trailing: false
   placeholder: 'Search...'
 ---
 ::
diff --git a/docs/content/3.components/radio-group.md b/docs/content/3.components/radio-group.md
index ad1669a4..919e1567 100644
--- a/docs/content/3.components/radio-group.md
+++ b/docs/content/3.components/radio-group.md
@@ -70,9 +70,9 @@ props:
 When using objects, you need to reference the `value` property of the object in the `v-model` directive or the `default-value` prop.
 ::
 
-#### Value Key
+### Value Key
 
-You can change the property that is used to set the value by using the `value-key` prop.
+You can change the property that is used to set the value by using the `value-key` prop. Defaults to `value`.
 
 ::component-code
 ---
diff --git a/docs/content/3.components/select-menu.md b/docs/content/3.components/select-menu.md
index a3349c6d..cbc6cbbc 100644
--- a/docs/content/3.components/select-menu.md
+++ b/docs/content/3.components/select-menu.md
@@ -8,15 +8,644 @@ links:
   - label: GitHub
     icon: i-simple-icons-github
     to: https://github.com/nuxt/ui/tree/v3/src/runtime/components/SelectMenu.vue
-navigation:
-  badge:
-    label: Todo
 ---
 
 ## Usage
 
+Use the `v-model` directive to control the value of the SelectMenu or the `default-value` prop to set the initial value when you do not need to control its state.
+
+::tip
+Use the SelectMenu component over a [Select](/components/select) to take advantage of Radix Vue's [Combobox](https://www.radix-vue.com/components/combobox.html) component that offers search capabilities and multiple selection.
+::
+
+### Items
+
+Use the `items` prop as an array of strings, numbers or booleans:
+
+::component-code
+---
+prettier: true
+ignore:
+  - modelValue
+  - items
+external:
+  - modelValue
+  - items
+props:
+  modelValue: 'Backlog'
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+You can also pass an array of objects with the following properties:
+
+- `label?: string`{lang="ts-type"}
+- [`type?: "label" | "separator" | "item"`{lang="ts-type"}](#with-typed-items)
+- [`icon?: string`{lang="ts-type"}](#with-icons-in-items)
+- [`avatar?: AvatarProps`{lang="ts-type"}](#with-avatar-in-items)
+- [`chip?: ChipProps`{lang="ts-type"}](#with-chip-in-items)
+- `disabled?: boolean`{lang="ts-type"}
+- `select?(e: Event): void`{lang="ts-type"}
+
+::component-code
+---
+ignore:
+  - modelValue.label
+  - items
+external:
+  - modelValue
+  - items
+props:
+  modelValue:
+    label: 'Todo'
+  items:
+    - label: 'Backlog'
+    - label: 'Todo'
+    - label: 'In Progress'
+    - label: 'Done'
+---
+::
+
+::note
+Unlike the [Select](/components/select) component, the SelectMenu expects the whole object to be passed to the `v-model` directive or the `default-value` prop by default.
+::
+
+You can also pass an array of arrays to the `items` prop to display separated groups of items.
+
+::component-code
+---
+prettier: true
+ignore:
+  - modelValue
+  - items
+external:
+  - modelValue
+  - items
+props:
+  modelValue: 'Apple'
+  items:
+    - - Apple
+      - Banana
+      - Blueberry
+      - Grapes
+      - Pineapple
+    - - Aubergine
+      - Broccoli
+      - Carrot
+      - Courgette
+      - Leek
+---
+::
+
+### Value Key
+
+You can choose to bind a single property of the object rather than the whole object by using the `value-key` prop. Defaults to `undefined`.
+
+::component-code
+---
+collapse: true
+ignore:
+  - modelValue
+  - valueKey
+  - items
+external:
+  - modelValue
+  - items
+props:
+  modelValue: 'todo'
+  valueKey: 'id'
+  items:
+    - label: 'Backlog'
+      id: 'backlog'
+    - label: 'Todo'
+      id: 'todo'
+    - label: 'In Progress'
+      id: 'in_progress'
+    - label: 'Done'
+      id: 'done'
+---
+::
+
+### Multiple
+
+Use the `multiple` prop to allow multiple selections, the selected items will be separated by a comma in the trigger.
+
+::component-code
+---
+prettier: true
+ignore:
+  - modelValue
+  - items
+  - multiple
+external:
+  - modelValue
+  - items
+props:
+  modelValue:
+    - Backlog
+    - Todo
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+  multiple: true
+---
+::
+
+::caution
+Ensure to pass an array to the `default-value` prop or the `v-model` directive.
+::
+
+### Placeholder
+
+Use the `placeholder` prop to set a placeholder text.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+ignore:
+  - items
+props:
+  placeholder: 'Select status'
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+### Search Input
+
+Use the `search-input` prop to customize the search input. Defaults to `{ placeholder: 'Search...' }`{lang="ts-type"}.
+
+::component-code
+---
+prettier: true
+ignore:
+  - modelValue.label
+  - modelValue.icon
+  - items
+external:
+  - items
+  - modelValue
+props:
+  modelValue:
+    label: 'Backlog'
+    icon: 'i-heroicons-question-mark-circle'
+  searchInput:
+    placeholder: 'Filter...'
+  items:
+    - label: Backlog
+      icon: 'i-heroicons-question-mark-circle'
+    - label: Todo
+      icon: 'i-heroicons-plus-circle'
+    - label: In Progress
+      icon: 'i-heroicons-arrow-up-circle'
+    - label: Done
+      icon: 'i-heroicons-check-circle'
+---
+::
+
+::tip
+You can set the `search-input` prop to `false` to hide the search input.
+::
+
+### Content
+
+Use the `content` prop to control how the SelectMenu content is rendered, like its `align` or `side` for example.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+items:
+  content.align:
+    - start
+    - center
+    - end
+  content.side:
+    - right
+    - left
+    - top
+    - bottom
+props:
+  modelValue: Backlog
+  content:
+    align: center
+    side: bottom
+    sideOffset: 8
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+### Color
+
+Use the `color` prop to change the ring color when the Select is focused.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  color: gray
+  highlight: true
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+::note
+The `highlight` prop is used here to show the focus state. It's used internally when a validation error occurs.
+::
+
+### Variant
+
+Use the `variant` prop to change the variant of the Select.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  color: gray
+  variant: subtle
+  highlight: false
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+### Size
+
+Use the `size` prop to change the size of the Select.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  size: xl
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+### Icon
+
+Use the `icon` prop to show an [Icon](/components/icon) inside the Select.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  icon: 'i-heroicons-magnifying-glass'
+  size: md
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+### Trailing Icon
+
+Use the `trailing-icon` prop to customize the trailing icon. Defaults to `i-heroicons-chevron-down-20-solid`.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  trailingIcon: 'i-heroicons-arrow-small-right'
+  size: md
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+::tip{to="/getting-started/icons#theme"}
+You can customize this icon globally in your `app.config.ts` under `ui.icons.chevronDown` key.
+::
+
+### Selected Icon
+
+Use the `selected-icon` prop to customize the icon when an item is selected. Defaults to `i-heroicons-check-20-solid`.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  selectedIcon: 'i-heroicons-fire'
+  size: md
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+::tip{to="/getting-started/icons#theme"}
+You can customize this icon globally in your `app.config.ts` under `ui.icons.check` key.
+::
+
+### Loading
+
+Use the `loading` prop to show a loading icon on the Select.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  loading: true
+  trailing: false
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+### Loading Icon
+
+Use the `loading-icon` prop to customize the loading icon. Defaults to `i-heroicons-arrow-path-20-solid`.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+  - modelValue
+ignore:
+  - items
+  - modelValue
+props:
+  modelValue: 'Backlog'
+  loading: true
+  loadingIcon: 'i-heroicons-arrow-path-rounded-square'
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
+::tip{to="/getting-started/icons#theme"}
+You can customize this icon globally in your `app.config.ts` under `ui.icons.loading` key.
+::
+
+### Disabled
+
+Use the `disabled` prop to disable the Select.
+
+::component-code
+---
+prettier: true
+external:
+  - items
+ignore:
+  - items
+  - placeholder
+props:
+  disabled: true
+  placeholder: 'Select status'
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+---
+::
+
 ## Examples
 
+### With typed items
+
+You can use the `type` property with `separator` to display a separator between items or `label` to display a label.
+
+::component-code
+---
+collapse: true
+ignore:
+  - modelValue
+  - items
+external:
+  - items
+  - modelValue
+props:
+  modelValue: 'Apple'
+  items:
+    - type: 'label'
+      label: 'Fruits'
+    - Apple
+    - Banana
+    - Blueberry
+    - Grapes
+    - Pineapple
+    - type: 'separator'
+    - type: 'label'
+      label: 'Vegetables'
+    - Aubergine
+    - Broccoli
+    - Carrot
+    - Courgette
+    - Leek
+---
+::
+
+### With icons in items
+
+You can use the `icon` property to display an [Icon](/components/icon) inside the items.
+
+::component-example
+---
+collapse: true
+name: 'select-menu-items-icon-example'
+---
+::
+
+::tip
+You can also use the `#leading` slot to display the selected icon, like in the next example.
+::
+
+### With avatar in items
+
+You can use the `avatar` property to display an [Avatar](/components/avatar) inside the items.
+
+::component-example
+---
+collapse: true
+name: 'select-menu-items-avatar-example'
+---
+::
+
+::note
+In this example, the `#leading` slot is used to display the selected avatar.
+::
+
+### With chip in items
+
+You can use the `chip` property to display a [Chip](/components/chip) inside the items.
+
+::component-example
+---
+collapse: true
+name: 'select-menu-items-chip-example'
+---
+::
+
+::note
+In this example, the `#leading` slot is used to display the selected chip.
+::
+
+### Control open state
+
+You can control the open state by using the `default-open` prop or the `v-model:open` directive.
+
+::component-example
+---
+name: 'select-menu-open-example'
+---
+::
+
+::note
+In this example, press :kbd{value="O"} to toggle the SelectMenu.
+::
+
+### Control search term
+
+Use the `v-model:search-term` directive to control the search term.
+
+::component-example
+---
+name: 'select-menu-search-term-example'
+---
+::
+
+### With rotating icon
+
+Here is an example with a rotating icon that indicates the open state of the SelectMenu.
+
+::component-example
+---
+name: 'select-menu-icon-example'
+---
+::
+
+### With fetched items
+
+You can fetch items from an API and use them in the SelectMenu.
+
+::component-example
+---
+collapse: true
+name: 'select-menu-fetch-example'
+---
+::
+
+### Without internal search
+
+Set the `filter` prop to `false` to disable the internal search and use your own search logic.
+
+::component-example
+---
+collapse: true
+name: 'select-menu-filter-example'
+---
+::
+
+::note
+This example uses [refDebounced](https://vueuse.org/shared/refDebounced/#refdebounced) to debounce the API calls.
+::
+
+### With custom search
+
+Use the `filter` prop with an array of fields to filter on.
+
+::component-example
+---
+collapse: true
+name: 'select-menu-filter-fields-example'
+---
+::
+
 ## API
 
 ### Props
diff --git a/docs/content/3.components/select.md b/docs/content/3.components/select.md
index fb0f8305..65c766b2 100644
--- a/docs/content/3.components/select.md
+++ b/docs/content/3.components/select.md
@@ -19,6 +19,7 @@ Use the `items` prop as an array of strings, numbers or booleans:
 
 ::component-code
 ---
+prettier: true
 ignore:
   - modelValue
   - items
@@ -39,15 +40,14 @@ You can also pass an array of objects with the following properties:
 
 - `label?: string`{lang="ts-type"}
 - [`value?: string`{lang="ts-type"}](#value-key)
-- [`type?: "label" | "separator" | "item"`{lang="ts-type"}](#items-type)
-- [`icon?: string`{lang="ts-type"}](#items-icon)
-- [`avatar?: AvatarProps`{lang="ts-type"}](#items-avatar)
-- [`chip?: ChipProps`{lang="ts-type"}](#items-chip)
+- [`type?: "label" | "separator" | "item"`{lang="ts-type"}](#with-typed-items)
+- [`icon?: string`{lang="ts-type"}](#with-icons-in-items)
+- [`avatar?: AvatarProps`{lang="ts-type"}](#with-avatar-in-items)
+- [`chip?: ChipProps`{lang="ts-type"}](#with-chip-in-items)
 - `disabled?: boolean`{lang="ts-type"}
 
 ::component-code
 ---
-collapse: true
 ignore:
   - modelValue
   - items
@@ -72,49 +72,19 @@ props:
 When using objects, you need to reference the `value` property of the object in the `v-model` directive or the `default-value` prop.
 ::
 
-#### Value Key
-
-You can change the property that is used to set the value by using the `value-key` prop.
-
-::component-code
----
-collapse: true
-ignore:
-  - modelValue
-  - valueKey
-  - items
-external:
-  - modelValue
-  - items
-props:
-  valueKey: 'id'
-  modelValue: 'backlog'
-  items:
-    - label: 'Backlog'
-      id: 'backlog'
-    - label: 'Todo'
-      id: 'todo'
-    - label: 'In Progress'
-      id: 'in_progress'
-    - label: 'Done'
-      id: 'done'
----
-::
-
-#### Group items
-
-You can pass an array of arrays to the `items` prop to display separated groups of items.
+You can also pass an array of arrays to the `items` prop to display separated groups of items.
 
 ::component-code
 ---
 prettier: true
 ignore:
-  - defaultValue
+  - modelValue
   - items
 external:
+  - modelValue
   - items
 props:
-  defaultValue: 'Apple'
+  modelValue: 'Apple'
   items:
     - - Apple
       - Banana
@@ -129,89 +99,34 @@ props:
 ---
 ::
 
-#### Items Type
+### Value Key
 
-You can use the `type` property with `separator` to display a separator between items or `label` to display a label.
+You can change the property that is used to set the value by using the `value-key` prop. Defaults to `value`.
 
 ::component-code
 ---
-prettier: true
-collapse: true
 ignore:
-  - defaultValue
+  - modelValue
+  - valueKey
   - items
 external:
+  - modelValue
   - items
 props:
-  defaultValue: 'Apple'
+  modelValue: 'backlog'
+  valueKey: 'id'
   items:
-    - type: 'label'
-      label: 'Fruits'
-    - Apple
-    - Banana
-    - Blueberry
-    - Grapes
-    - Pineapple
-    - type: 'separator'
-    - type: 'label'
-      label: 'Vegetables'
-    - Aubergine
-    - Broccoli
-    - Carrot
-    - Courgette
-    - Leek
+    - label: 'Backlog'
+      id: 'backlog'
+    - label: 'Todo'
+      id: 'todo'
+    - label: 'In Progress'
+      id: 'in_progress'
+    - label: 'Done'
+      id: 'done'
 ---
 ::
 
-#### Items Icon
-
-You can use the `icon` property to display an [Icon](/components/icon) inside the items.
-
-::component-example
----
-collapse: true
-name: 'select-items-icon-example'
----
-::
-
-::note
-In this example, the icon is computed from the `value` property of the selected item.
-::
-
-::tip
-You can also use the `#leading` slot to display the selected icon, like in the next example.
-::
-
-#### Items Avatar
-
-You can use the `avatar` property to display an [Avatar](/components/avatar) inside the items.
-
-::component-example
----
-collapse: true
-name: 'select-items-avatar-example'
----
-::
-
-::note
-In this example, the `#leading` slot is used to display the selected avatar.
-::
-
-#### Items Chip
-
-You can use the `chip` property to display a [Chip](/components/chip) inside the items.
-
-::component-example
----
-collapse: true
-name: 'select-items-chip-example'
----
-::
-
-::note
-In this example, the `#leading` slot is used to display the selected chip.
-::
-
 ### Placeholder
 
 Use the `placeholder` prop to set a placeholder text.
@@ -233,6 +148,54 @@ props:
 ---
 ::
 
+### Content
+
+Use the `content` prop to control how the Select content is rendered, like its its `align`, `side` or `position` for example. Defaults to `popper` to match other components.
+
+::caution
+The `content.align`, `content.side`, etc. properties only apply when `content.position` is set to `popper`.
+::
+
+::component-code
+---
+prettier: true
+external:
+  - items
+ignore:
+  - items
+  - defaultValue
+items:
+  content.position:
+    - 'item-aligned'
+    - 'popper'
+  content.align:
+    - start
+    - center
+    - end
+  content.side:
+    - right
+    - left
+    - top
+    - bottom
+props:
+  content:
+    position: 'item-aligned'
+    align: center
+    side: bottom
+    sideOffset: 8
+  items:
+    - Backlog
+    - Todo
+    - In Progress
+    - Done
+  defaultValue: 'Todo'
+---
+::
+
+::note{to="https://www.radix-vue.com/components/select.html#change-the-positioning-mode"}
+Read more about the `content.position` prop in the [Radix Vue documentation](https://www.radix-vue.com/components/select.html#change-the-positioning-mode).
+::
+
 ### Color
 
 Use the `color` prop to change the ring color when the Select is focused.
@@ -428,7 +391,6 @@ ignore:
 props:
   loading: true
   loadingIcon: 'i-heroicons-arrow-path-rounded-square'
-  trailing: false
   defaultValue: 'Backlog'
   items:
     - Backlog
@@ -467,6 +429,89 @@ props:
 
 ## Examples
 
+### With typed items
+
+You can use the `type` property with `separator` to display a separator between items or `label` to display a label.
+
+::component-code
+---
+collapse: true
+ignore:
+  - modelValue
+  - items
+external:
+  - modelValue
+  - items
+props:
+  modelValue: 'Apple'
+  items:
+    - type: 'label'
+      label: 'Fruits'
+    - Apple
+    - Banana
+    - Blueberry
+    - Grapes
+    - Pineapple
+    - type: 'separator'
+    - type: 'label'
+      label: 'Vegetables'
+    - Aubergine
+    - Broccoli
+    - Carrot
+    - Courgette
+    - Leek
+---
+::
+
+### With icons in items
+
+You can use the `icon` property to display an [Icon](/components/icon) inside the items.
+
+::component-example
+---
+collapse: true
+name: 'select-items-icon-example'
+---
+::
+
+::note
+In this example, the icon is computed from the `value` property of the selected item.
+::
+
+::tip
+You can also use the `#leading` slot to display the selected icon, like in the next example.
+::
+
+### With avatar in items
+
+You can use the `avatar` property to display an [Avatar](/components/avatar) inside the items.
+
+::component-example
+---
+collapse: true
+name: 'select-items-avatar-example'
+---
+::
+
+::note
+In this example, the `#leading` slot is used to display the selected avatar.
+::
+
+### With chip in items
+
+You can use the `chip` property to display a [Chip](/components/chip) inside the items.
+
+::component-example
+---
+collapse: true
+name: 'select-items-chip-example'
+---
+::
+
+::note
+In this example, the `#leading` slot is used to display the selected chip.
+::
+
 ### Control open state
 
 You can control the open state by using the `default-open` prop or the `v-model:open` directive.
@@ -498,6 +543,7 @@ You can fetch items from an API and use them in the Select.
 ::component-example
 ---
 name: 'select-fetch-example'
+collapse: true
 ---
 ::
 
diff --git a/docs/nuxt.config.ts b/docs/nuxt.config.ts
index 7b1a47a3..4f0f9145 100644
--- a/docs/nuxt.config.ts
+++ b/docs/nuxt.config.ts
@@ -171,6 +171,7 @@ export default defineNuxtConfig({
         'UProgress',
         'URadioGroup',
         'USelect',
+        'USelectMenu',
         'USeparator',
         'USlider',
         'USlideover',