Forms

Select

Display a select field.

Usage

The Select component is a wrapper around the native <select> HTML element. For more advanced use cases like searching or multiple selection, consider using the SelectMenu component.

Use a v-model to make the Select reactive alongside the options prop to pass an array of strings or objects.

<script setup>
const countries = ['United States', 'Canada', 'Mexico']

const country = ref(countries[0])
</script>

<template>
  <USelect v-model="country" :options="countries" />
</template>

When using objects, you can configure which field will be used for display through the option-attribute prop that defaults to label and which field will be used for comparison through the value-attribute prop that defaults to value.

Adding a disabled key to the objects will control the disabled state of the option.

<script setup>
const countries = [{
  name: 'United States',
  value: 'US'
}, {
  name: 'Canada',
  value: 'CA',
  disabled: true
}, {
  name: 'Mexico',
  value: 'MX'
}]

const country = ref('CA')
</script>

<template>
  <USelect v-model="country" :options="countries" option-attribute="name" />
</template>

Style

Use the color and variant props to change the visual style of the Select.

<USelect
  color="primary"
  variant="outline"
  :options="['United States', 'Canada', 'Mexico']"
/>

Besides all the colors from the ui.colors object, you can also use the white (default) and gray colors with their pre-defined variants.

White

<USelect
  color="white"
  variant="outline"
  :options="['United States', 'Canada', 'Mexico']"
/>

Gray

<USelect
  color="gray"
  variant="outline"
  :options="['United States', 'Canada', 'Mexico']"
/>

Size

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

<USelect size="sm" :options="['United States', 'Canada', 'Mexico']" />

Placeholder

Use the placeholder prop to set a placeholder text.

<USelect
  placeholder="Search..."
  :options="['United States', 'Canada', 'Mexico']"
/>

Icon

Use any icon from Iconify by setting the icon prop by using this pattern: i-{collection_name}-{icon_name}.

Use the trailing-icon prop to set a different icon or change it globally in ui.select.default.trailingIcon. Defaults to i-heroicons-chevron-down-20-solid.

<USelect
  icon="i-heroicons-magnifying-glass-20-solid"
  color="white"
  size="sm"
  :options="['United States', 'Canada', 'Mexico']"
  placeholder="Search..."
/>

Disabled

Use the disabled prop to disable the Select.

<USelect
  disabled
  :options="['United States', 'Canada', 'Mexico']"
  placeholder="Search..."
/>

Add a disabled key with a truthy value to the options array of object to disable a single option.

Loading

Use the loading prop to show a loading icon and disable the Input.

Use the loading-icon prop to set a different icon or change it globally in ui.select.default.loadingIcon. Defaults to i-heroicons-arrow-path-20-solid.

<USelect
  loading
  icon="i-heroicons-magnifying-glass-20-solid"
  :options="['United States', 'Canada', 'Mexico']"
  placeholder="Search..."
/>

Slots

leading

Use the #leading slot to set the content of the leading icon.

<USelect
  :options="['United States', 'Canada', 'Mexico']"
  placeholder="Search..."
>
  <template #leading>
    <UAvatar
      src="https://avatars.githubusercontent.com/u/739984?v=4"
      size="3xs"
    />
  </template>
</USelect>

trailing

Use the #trailing slot to set the content of the trailing icon.

<USelect placeholder="Search...">
  <template #trailing>
    <UIcon name="i-heroicons-arrows-up-down-20-solid" />
  </template>
</USelect>

Props

name
string
null
ui
any
undefined
color
string
config.default.color
size
"md" | "2xs" | "xs" | "sm" | "lg" | "xl"
null
icon
string
null
id
string
null
modelValue
string | number | Record<string, any>
""
placeholder
string
null
variant
"outline" | "none"
config.default.variant
loadingIcon
string
config.default.loadingIcon
leadingIcon
string
null
trailingIcon
string
config.default.trailingIcon
options
unknown[]
[]
optionAttribute
string
"label"
valueAttribute
string
"value"
selectClass
string
null
required
boolean
false
disabled
boolean
false
leading
boolean
false
trailing
boolean
false
loading
boolean
false
padded
boolean
true

Config

{
  "wrapper": "relative",
  "base": "relative block w-full disabled:cursor-not-allowed disabled:opacity-75 focus:outline-none border-0",
  "rounded": "rounded-md",
  "placeholder": "text-gray-900 dark:text-white",
  "size": {
    "2xs": "text-xs",
    "xs": "text-xs",
    "sm": "text-sm",
    "md": "text-sm",
    "lg": "text-sm",
    "xl": "text-base"
  },
  "gap": {
    "2xs": "gap-x-1",
    "xs": "gap-x-1.5",
    "sm": "gap-x-1.5",
    "md": "gap-x-2",
    "lg": "gap-x-2.5",
    "xl": "gap-x-2.5"
  },
  "padding": {
    "2xs": "px-2 py-1",
    "xs": "px-2.5 py-1.5",
    "sm": "px-2.5 py-1.5",
    "md": "px-3 py-2",
    "lg": "px-3.5 py-2.5",
    "xl": "px-3.5 py-2.5"
  },
  "leading": {
    "padding": {
      "2xs": "ps-7",
      "xs": "ps-8",
      "sm": "ps-9",
      "md": "ps-10",
      "lg": "ps-11",
      "xl": "ps-12"
    }
  },
  "trailing": {
    "padding": {
      "2xs": "pe-7",
      "xs": "pe-8",
      "sm": "pe-9",
      "md": "pe-10",
      "lg": "pe-11",
      "xl": "pe-12"
    }
  },
  "color": {
    "white": {
      "outline": "shadow-sm bg-white dark:bg-gray-900 text-gray-900 dark:text-white ring-1 ring-inset ring-gray-300 dark:ring-gray-700 focus:ring-2 focus:ring-primary-500 dark:focus:ring-primary-400"
    },
    "gray": {
      "outline": "shadow-sm bg-gray-50 dark:bg-gray-800 text-gray-900 dark:text-white ring-1 ring-inset ring-gray-300 dark:ring-gray-700 focus:ring-2 focus:ring-primary-500 dark:focus:ring-primary-400"
    }
  },
  "variant": {
    "outline": "shadow-sm bg-transparent text-gray-900 dark:text-white ring-1 ring-inset ring-{color}-500 dark:ring-{color}-400 focus:ring-2 focus:ring-{color}-500 dark:focus:ring-{color}-400",
    "none": "bg-transparent focus:ring-0 focus:shadow-none"
  },
  "icon": {
    "base": "flex-shrink-0 text-gray-400 dark:text-gray-500",
    "color": "text-{color}-500 dark:text-{color}-400",
    "size": {
      "2xs": "h-4 w-4",
      "xs": "h-4 w-4",
      "sm": "h-5 w-5",
      "md": "h-5 w-5",
      "lg": "h-5 w-5",
      "xl": "h-6 w-6"
    },
    "leading": {
      "wrapper": "absolute inset-y-0 start-0 flex items-center",
      "pointer": "pointer-events-none",
      "padding": {
        "2xs": "ps-2",
        "xs": "ps-2.5",
        "sm": "ps-2.5",
        "md": "ps-3",
        "lg": "ps-3.5",
        "xl": "ps-3.5"
      }
    },
    "trailing": {
      "wrapper": "absolute inset-y-0 end-0 flex items-center",
      "pointer": "pointer-events-none",
      "padding": {
        "2xs": "pe-2",
        "xs": "pe-2.5",
        "sm": "pe-2.5",
        "md": "pe-3",
        "lg": "pe-3.5",
        "xl": "pe-3.5"
      }
    }
  },
  "default": {
    "size": "sm",
    "color": "white",
    "variant": "outline",
    "loadingIcon": "i-heroicons-arrow-path-20-solid",
    "trailingIcon": "i-heroicons-chevron-down-20-solid"
  }
}