docs(select-menu): update

2026-01-14 20:19:34 +01:00 · 2024-09-25 19:07:21 +02:00
parent 183207c2b8
commit fb8e6a6a66
21 changed files with 1054 additions and 123 deletions
--- 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
 ---
 ::