arthur/ui
1
0
Fork 0
mirror of https://github.com/ArthurDanjou/ui.git synced 2026-01-14 12:14:41 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
3496b2d5414065ca797611cc4c24ad20c222fa5f
ui/docs/content/3.components/select.md

11 KiB
Raw Blame History

description, links
description links
A select element to choose from a list of options.
label icon to
Select i-custom-radix-vue https://www.radix-vue.com/components/select.html
label icon to
GitHub i-simple-icons-github https://github.com/nuxt/ui/tree/v3/src/runtime/components/Select.vue

Usage

Use the v-model directive to control the value of the Select or the default-value prop to set the initial value when you do not need to control its state.

Items

Use the items prop as an array of strings, numbers or booleans:

::component-code

prettier: true ignore:

  • modelValue
  • items
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

You can also pass an array of objects with the following properties:

::component-code

ignore:

  • modelValue
  • items
  • class external:
  • items
  • modelValue props: modelValue: 'backlog' items:
    • label: 'Backlog' value: 'backlog'
    • label: 'Todo' value: 'todo'
    • label: 'In Progress' value: 'in_progress'
    • label: 'Done' value: 'done' class: 'w-48'

::

::caution When using objects, you need to reference the value property of the object in the v-model directive or the default-value prop. ::

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
  • class external:
  • items
  • modelValue props: modelValue: 'Apple' items:
      • Apple
      • Banana
      • Blueberry
      • Grapes
      • Pineapple
      • Aubergine
      • Broccoli
      • Carrot
      • Courgette
      • Leek class: 'w-48'

::

Value Key

You can change the property that is used to set the value by using the value-key prop. Defaults to value.

::component-code

ignore:

  • modelValue
  • valueKey
  • items
  • class external:
  • items
  • modelValue props: modelValue: 'backlog' valueKey: 'id' items:
    • label: 'Backlog' id: 'backlog'
    • label: 'Todo' id: 'todo'
    • label: 'In Progress' id: 'in_progress'
    • label: 'Done' id: 'done' class: 'w-48'

::

Placeholder

Use the placeholder prop to set a placeholder text.

::component-code

prettier: true ignore:

  • items
  • class external:
  • items props: placeholder: 'Select status' items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

Content

Use the content prop to control how the Select content is rendered, like its align, side or position for example.

::warning The content.align, content.side, etc. properties only apply when content.position is set to popper. ::

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue items: content.position:
    • 'item-aligned'
    • 'popper' content.align:
    • start
    • center
    • end content.side:
    • right
    • left
    • top
    • bottom props: modelValue: 'Todo' content: position: 'item-aligned' align: center side: bottom sideOffset: 8 items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

::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. ::

Color

Use the color prop to change the ring color when the Select is focused.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' color: neutral highlight: true items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

::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 ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' color: neutral variant: subtle highlight: false items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

Size

Use the size prop to change the size of the Select.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' size: xl items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

Icon

Use the icon prop to show an Icon inside the Select.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' icon: 'i-lucide-search' size: md items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

Trailing Icon

Use the trailing-icon prop to customize the trailing Icon. Defaults to i-lucide-chevron-down.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' trailingIcon: 'i-lucide-arrow-down' size: md items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

::framework-only #nuxt :::tip{to="/getting-started/icons/nuxt#theme"} You can customize this icon globally in your app.config.ts under ui.icons.chevronDown key. :::

#vue :::tip{to="/getting-started/icons/vue#theme"} You can customize this icon globally in your vite.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-lucide-check.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' selectedIcon: 'i-lucide-flame' size: md items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

::framework-only #nuxt :::tip{to="/getting-started/icons/nuxt#theme"} You can customize this icon globally in your app.config.ts under ui.icons.check key. :::

#vue :::tip{to="/getting-started/icons/vue#theme"} You can customize this icon globally in your vite.config.ts under ui.icons.check key. ::: ::

Avatar

Use the avatar prop to show an Avatar inside the Select.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Nuxt' avatar: src: 'https://github.com/nuxt.png' items:
    • Nuxt
    • NuxtHub
    • NuxtLabs
    • Nuxt Modules
    • Nuxt Community class: 'w-48'

::

Loading

Use the loading prop to show a loading icon on the Select.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' loading: true trailing: false items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

Loading Icon

Use the loading-icon prop to customize the loading icon. Defaults to i-lucide-refresh-ccw.

::component-code

prettier: true ignore:

  • items
  • modelValue
  • class external:
  • items
  • modelValue props: modelValue: 'Backlog' loading: true loadingIcon: 'i-lucide-repeat-2' items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

::framework-only #nuxt :::tip{to="/getting-started/icons/nuxt#theme"} You can customize this icon globally in your app.config.ts under ui.icons.loading key. :::

#vue :::tip{to="/getting-started/icons/vue#theme"} You can customize this icon globally in your vite.config.ts under ui.icons.loading key. ::: ::

Disabled

Use the disabled prop to disable the Select.

::component-code

prettier: true ignore:

  • items
  • placeholder
  • class external:
  • items props: disabled: true placeholder: 'Select status' items:
    • Backlog
    • Todo
    • In Progress
    • Done class: 'w-48'

::

Examples

With items type

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
  • class 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 class: 'w-48'

::

With icons in items

You can use the icon property to display an 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. ::

With avatar in items

You can use the avatar property to display an Avatar inside the items.

::component-example

collapse: true name: 'select-items-avatar-example'

::

::note In this example, the avatar is computed from the value property of the selected item. ::

::tip You can also use the #leading slot to display the selected avatar. ::

With chip in items

You can use the chip property to display a 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.

::component-example

name: 'select-open-example'

::

::note In this example, leveraging defineShortcuts, you can toggle the Select by pressing :kbd{value="O"}. ::

With rotating icon

Here is an example with a rotating icon that indicates the open state of the Select.

::component-example

name: 'select-icon-example'

::

With fetched items

You can fetch items from an API and use them in the Select.

::component-example

name: 'select-fetch-example' collapse: true

::

API

Props

:component-props

Slots

:component-slots

Emits

:component-emits

Theme

:component-theme

Reference in New Issue View Git Blame Copy Permalink