v3.0.0-alpha.5
Components

Select

SelectGitHub
A select element to choose from a list of options.

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:

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
const value = ref('Backlog')
</script>

<template>
  <USelect v-model="value" :items="items" />
</template>

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

<script setup lang="ts">
const items = ref([
  {
    label: 'Backlog',
    value: 'backlog'
  },
  {
    label: 'Todo',
    value: 'todo'
  },
  {
    label: 'In Progress',
    value: 'in_progress'
  },
  {
    label: 'Done',
    value: 'done'
  }
])
const value = ref('backlog')
</script>

<template>
  <USelect v-model="value" :items="items" />
</template>
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.

<script setup lang="ts">
const items = ref([
  ['Apple', 'Banana', 'Blueberry', 'Grapes', 'Pineapple'],
  ['Aubergine', 'Broccoli', 'Carrot', 'Courgette', 'Leek']
])
const value = ref('Apple')
</script>

<template>
  <USelect v-model="value" :items="items" />
</template>

Value Key

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

<script setup lang="ts">
const items = ref([
  {
    label: 'Backlog',
    id: 'backlog'
  },
  {
    label: 'Todo',
    id: 'todo'
  },
  {
    label: 'In Progress',
    id: 'in_progress'
  },
  {
    label: 'Done',
    id: 'done'
  }
])
const value = ref('backlog')
</script>

<template>
  <USelect v-model="value" value-key="id" :items="items" />
</template>

Placeholder

Use the placeholder prop to set a placeholder text.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect placeholder="Select status" :items="items" />
</template>

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.

The content.align, content.side, etc. properties only apply when content.position is set to popper.
<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    :content="{
      position: 'item-aligned',
      align: 'center',
      side: 'bottom',
      sideOffset: 8
    }"
    :items="items"
    default-value="Todo"
  />
</template>
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.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect color="gray" highlight default-value="Backlog" :items="items" />
</template>
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.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    color="gray"
    variant="subtle"
    default-value="Backlog"
    :items="items"
  />
</template>

Size

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

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect size="xl" default-value="Backlog" :items="items" />
</template>

Icon

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

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    icon="i-heroicons-magnifying-glass"
    default-value="Backlog"
    :items="items"
  />
</template>

Trailing Icon

Use the trailing-icon prop to customize the trailing Icon. Defaults to i-heroicons-chevron-down-20-solid.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    trailing-icon="i-heroicons-arrow-small-down-20-solid"
    default-value="Backlog"
    :items="items"
  />
</template>
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.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    selected-icon="i-heroicons-fire"
    default-value="Backlog"
    :items="items"
  />
</template>
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.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect loading default-value="Backlog" :items="items" />
</template>

Loading Icon

Use the loading-icon prop to customize the loading icon. Defaults to i-heroicons-arrow-path-20-solid.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    loading
    loading-icon="i-heroicons-arrow-path-rounded-square"
    default-value="Backlog"
    :items="items"
  />
</template>
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.

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect disabled placeholder="Select status" :items="items" />
</template>

Examples

With typed items

You can use the type property with separator to display a separator between items or label to display a label.

<script setup lang="ts">
const items = ref([
  {
    type: 'label',
    label: 'Fruits'
  },
  'Apple',
  'Banana',
  'Blueberry',
  'Grapes',
  'Pineapple',
  {
    type: 'separator'
  },
  {
    type: 'label',
    label: 'Vegetables'
  },
  'Aubergine',
  'Broccoli',
  'Carrot',
  'Courgette',
  'Leek'
])
const value = ref('Apple')
</script>

<template>
  <USelect v-model="value" :items="items" />
</template>

With icons in items

You can use the icon property to display an Icon inside the items.

<script setup lang="ts">
const selected = ref('backlog')
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 icon = computed(() => items.value.find(item => item.value === selected.value)?.icon)
</script>

<template>
  <USelect v-model="selected" :icon="icon" :items="items" class="w-40" />
</template>
In this example, the icon is computed from the value property of the selected item.
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 inside the items.

<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'
    }
  }
])

function getAvatar(value: string) {
  return items.value.find(item => item.value === value)?.avatar
}
</script>

<template>
  <USelect default-value="benjamincanac" :items="items" class="w-40">
    <template #leading="{ modelValue, ui }">
      <UAvatar
        v-if="modelValue"
        v-bind="getAvatar(modelValue)"
        :size="ui.itemLeadingAvatarSize()"
        :class="ui.itemLeadingAvatar()"
      />
    </template>
  </USelect>
</template>
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 inside the items.

<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
    }
  }
])

function getChip(value: string) {
  return items.value.find(item => item.value === value)?.chip
}
</script>

<template>
  <USelect default-value="bug" :items="items" class="w-40">
    <template #leading="{ modelValue, ui }">
      <UChip
        v-if="modelValue"
        v-bind="getChip(modelValue)"
        inset
        standalone
        :size="ui.itemLeadingChipSize()"
        :class="ui.itemLeadingChip()"
      />
    </template>
  </USelect>
</template>
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.

<script setup lang="ts">
const open = ref(false)
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])

defineShortcuts({
  o: () => open.value = !open.value
})
</script>

<template>
  <USelect v-model:open="open" default-value="Backlog" :items="items" />
</template>
In this example, press O to toggle the Select.

With rotating icon

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

<script setup lang="ts">
const items = ref(['Backlog', 'Todo', 'In Progress', 'Done'])
</script>

<template>
  <USelect
    default-value="Backlog"
    :items="items"
    :ui="{
      trailingIcon: 'group-data-[state=open]:rotate-180 transition-transform duration-200'
    }"
  />
</template>

With fetched items

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

<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
})

function getUserAvatar(value: string) {
  return users.value?.find(user => user.value === value)?.avatar || {}
}
</script>

<template>
  <USelect
    :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="getUserAvatar(modelValue)"
        :size="ui.itemLeadingAvatarSize()"
        :class="ui.itemLeadingAvatar()"
      />
    </template>
  </USelect>
</template>

API

Props

Prop Default Type
id

string

placeholder

string

The placeholder text when the select is empty.

color

primary

"error" | "primary" | "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "gray"

variant

outline

"outline" | "soft" | "subtle" | "ghost" | "none"

size

md

"md" | "xs" | "sm" | "lg" | "xl"

trailingIcon

appConfig.ui.icons.chevronDown

string

The icon displayed to open the menu.

selectedIcon

appConfig.ui.icons.check

string

The icon displayed when an item is selected.

content

{ side: 'bottom', sideOffset: 8, position: 'popper' }

Omit<SelectContentProps, "asChild" | "as" | "forceMount">

The content of the menu.

arrow

false

boolean | Omit<SelectArrowProps, "asChild" | "as">

Display an arrow alongside the menu.

portal

true

boolean

Render the menu in a portal.

valueKey

"value"

string

When items is an array of objects, select the field to use as the value.

items

(AcceptableValue | SelectItem)[] | (AcceptableValue | SelectItem)[][]

highlight

boolean

Highlight the ring color like a focus state.

defaultValue

string

The value of the select when initially rendered. Use when you do not need to control the state of the Select

modelValue

string

The controlled value of the Select. Can be bind as v-model.

disabled

boolean

When true, prevents the user from interacting with Select

open

boolean

The controlled open state of the Select. Can be bind as v-model:open.

defaultOpen

boolean

The open state of the select when it is initially rendered. Use when you do not need to control its open state.

required

boolean

When true, indicates that the user must select a value before the owning form can be submitted.

name

string

The name of the Select. Submitted with its owning form as part of a name/value pair.

autocomplete

string

Native html input autocomplete attribute.

icon

string

Display an icon based on the leading and trailing props.

leading

boolean

When true, the icon will be displayed on the left side.

leadingIcon

string

Display an icon on the left side.

trailing

boolean

When true, the icon will be displayed on the right side.

loading

boolean

When true, the loading icon will be displayed.

loadingIcon

appConfig.ui.icons.loading

string

The icon when the loading prop is true.

ui

PartialString<{ base: string[]; leading: "absolute inset-y-0 start-0 flex items-center"; leadingIcon: string; leadingAvatar: string; trailing: "absolute inset-y-0 end-0 flex items-center"; trailingIcon: string; ... 16 more ...; itemLabel: string; }>

Slots

Slot Type
leading

{ modelValue: string; open: boolean; ui: any; }

trailing

{ modelValue: string; open: boolean; ui: any; }

item

{ item: AcceptableValue | SelectItem; index: number; }

item-leading

{ item: AcceptableValue | SelectItem; index: number; }

item-label

{ item: AcceptableValue | SelectItem; index: number; }

item-trailing

{ item: AcceptableValue | SelectItem; index: number; }

Emits

Event Type
blur

[payload: FocusEvent]

change

[payload: Event]

focus

[payload: FocusEvent]

update:modelValue

[value: string]

update:open

[value: boolean]

Theme

app.config.ts
export default defineAppConfig({
  ui: {
    select: {
      slots: {
        base: [
          'relative group rounded-md inline-flex items-center focus:outline-none disabled:cursor-not-allowed disabled:opacity-75',
          'transition-colors'
        ],
        leading: 'absolute inset-y-0 start-0 flex items-center',
        leadingIcon: 'shrink-0 text-gray-400 dark:text-gray-500',
        leadingAvatar: 'shrink-0',
        trailing: 'absolute inset-y-0 end-0 flex items-center',
        trailingIcon: 'shrink-0 text-gray-400 dark:text-gray-500',
        value: 'truncate group-data-placeholder:text-current/50',
        arrow: 'fill-gray-200 dark:fill-gray-800',
        content: 'max-h-60 w-[--radix-popper-anchor-width] bg-white dark:bg-gray-900 shadow-lg rounded-md ring ring-gray-200 dark:ring-gray-800 overflow-hidden data-[state=open]:animate-[scale-in_100ms_ease-out] data-[state=closed]:animate-[scale-out_100ms_ease-in]',
        viewport: 'divide-y divide-gray-200 dark:divide-gray-800 scroll-py-1',
        group: 'p-1 isolate',
        empty: 'py-2 text-center text-sm text-gray-500 dark:text-gray-400',
        label: 'font-semibold text-gray-900 dark:text-white',
        separator: '-mx-1 my-1 h-px bg-gray-200 dark:bg-gray-800',
        item: [
          'group relative w-full flex items-center select-none outline-none before:absolute before:z-[-1] before:inset-px before:rounded-md data-disabled:cursor-not-allowed data-disabled:opacity-75 text-gray-700 dark:text-gray-200 data-highlighted:text-gray-900 dark:data-highlighted:text-white data-highlighted:before:bg-gray-50 dark:data-highlighted:before:bg-gray-800/50',
          'transition-colors before:transition-colors'
        ],
        itemLeadingIcon: [
          'shrink-0 text-gray-400 dark:text-gray-500 group-data-highlighted:text-gray-700 dark:group-data-highlighted:text-gray-200',
          'transition-colors'
        ],
        itemLeadingAvatar: 'shrink-0',
        itemLeadingAvatarSize: '',
        itemLeadingChip: 'shrink-0',
        itemLeadingChipSize: '',
        itemTrailing: 'ms-auto inline-flex gap-1.5 items-center',
        itemTrailingIcon: 'shrink-0',
        itemLabel: 'truncate'
      },
      variants: {
        buttonGroup: {
          horizontal: 'not-only:first:rounded-e-none not-only:last:rounded-s-none not-last:not-first:rounded-none',
          vertical: 'not-only:first:rounded-b-none not-only:last:rounded-t-none not-last:not-first:rounded-none'
        },
        size: {
          xs: {
            base: 'px-2 py-1 text-xs gap-1',
            leading: 'pl-2',
            trailing: 'pr-2',
            leadingIcon: 'size-4',
            trailingIcon: 'size-4',
            label: 'p-1 text-[10px]/3 gap-1',
            item: 'p-1 text-xs gap-1',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4'
          },
          sm: {
            base: 'px-2.5 py-1.5 text-xs gap-1.5',
            leading: 'pl-2.5',
            trailing: 'pr-2.5',
            leadingIcon: 'size-4',
            trailingIcon: 'size-4',
            label: 'p-1.5 text-[10px]/3 gap-1.5',
            item: 'p-1.5 text-xs gap-1.5',
            itemLeadingIcon: 'size-4',
            itemLeadingAvatarSize: '3xs',
            itemLeadingChip: 'size-4',
            itemLeadingChipSize: 'sm',
            itemTrailingIcon: 'size-4'
          },
          md: {
            base: 'px-2.5 py-1.5 text-sm gap-1.5',
            leading: 'pl-2.5',
            trailing: 'pr-2.5',
            leadingIcon: 'size-5',
            trailingIcon: 'size-5',
            label: 'p-1.5 text-xs gap-1.5',
            item: 'p-1.5 text-sm gap-1.5',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5'
          },
          lg: {
            base: 'px-3 py-2 text-sm gap-2',
            leading: 'pl-3',
            trailing: 'pr-3',
            leadingIcon: 'size-5',
            trailingIcon: 'size-5',
            label: 'p-2 text-xs gap-2',
            item: 'p-2 text-sm gap-2',
            itemLeadingIcon: 'size-5',
            itemLeadingAvatarSize: '2xs',
            itemLeadingChip: 'size-5',
            itemLeadingChipSize: 'md',
            itemTrailingIcon: 'size-5'
          },
          xl: {
            base: 'px-3 py-2 text-base gap-2',
            leading: 'pl-3',
            trailing: 'pr-3',
            leadingIcon: 'size-6',
            trailingIcon: 'size-6',
            label: 'p-2 text-sm gap-2',
            item: 'p-2 text-base gap-2',
            itemLeadingIcon: 'size-6',
            itemLeadingAvatarSize: 'xs',
            itemLeadingChip: 'size-6',
            itemLeadingChipSize: 'lg',
            itemTrailingIcon: 'size-6'
          }
        },
        variant: {
          outline: 'text-gray-900 dark:text-white bg-white dark:bg-gray-900 ring ring-inset ring-gray-300 dark:ring-gray-700',
          soft: 'text-gray-900 dark:text-white bg-gray-50 hover:bg-gray-100 focus:bg-gray-100 disabled:bg-gray-50 dark:bg-gray-800/50 dark:hover:bg-gray-800 dark:focus:bg-gray-800 dark:disabled:bg-gray-800/50',
          subtle: 'text-gray-900 dark:text-white bg-gray-100 dark:bg-gray-800 ring ring-inset ring-gray-300 dark:ring-gray-700',
          ghost: 'text-gray-900 dark:text-white hover:bg-gray-100 focus:bg-gray-100 disabled:bg-transparent dark:hover:bg-gray-800 dark:focus:bg-gray-800 dark:disabled:bg-transparent',
          none: 'text-gray-900 dark:text-white'
        },
        color: {
          primary: '',
          error: '',
          red: '',
          orange: '',
          amber: '',
          yellow: '',
          lime: '',
          green: '',
          emerald: '',
          teal: '',
          cyan: '',
          sky: '',
          blue: '',
          indigo: '',
          violet: '',
          purple: '',
          fuchsia: '',
          pink: '',
          rose: '',
          gray: ''
        },
        leading: {
          true: ''
        },
        trailing: {
          true: ''
        },
        loading: {
          true: ''
        },
        highlight: {
          true: ''
        },
        type: {
          file: 'file:mr-1.5 file:font-medium file:text-gray-500 dark:file:text-gray-400 file:outline-none'
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-primary-500 dark:focus-visible:ring-primary-400'
        },
        {
          color: 'primary',
          highlight: true,
          class: 'ring ring-inset ring-primary-500 dark:ring-primary-400'
        },
        {
          color: 'gray',
          variant: [
            'outline',
            'subtle'
          ],
          class: 'focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-gray-900 dark:focus-visible:ring-white'
        },
        {
          color: 'gray',
          highlight: true,
          class: 'ring ring-inset ring-gray-900 dark:ring-white'
        },
        {
          leading: true,
          size: 'xs',
          class: 'pl-7'
        },
        {
          leading: true,
          size: 'sm',
          class: 'pl-8'
        },
        {
          leading: true,
          size: 'md',
          class: 'pl-9'
        },
        {
          leading: true,
          size: 'lg',
          class: 'pl-10'
        },
        {
          leading: true,
          size: 'xl',
          class: 'pl-11'
        },
        {
          trailing: true,
          size: 'xs',
          class: 'pr-7'
        },
        {
          trailing: true,
          size: 'sm',
          class: 'pr-8'
        },
        {
          trailing: true,
          size: 'md',
          class: 'pr-9'
        },
        {
          trailing: true,
          size: 'lg',
          class: 'pr-10'
        },
        {
          trailing: true,
          size: 'xl',
          class: 'pr-11'
        },
        {
          loading: true,
          leading: true,
          class: {
            leadingIcon: 'animate-spin'
          }
        },
        {
          loading: true,
          leading: false,
          trailing: true,
          class: {
            trailingIcon: 'animate-spin'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary',
        variant: 'outline'
      }
    }
  }
})
Some colors in compoundVariants are omitted for readability. Check out the source code on GitHub.

RadioGroup

A set of radio buttons to select a single option from a list.

SelectMenu

An advanced searchable select element.