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 lang="ts">
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 lang="ts">
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.

White

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

Gray

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

Size

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

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

Placeholder

Use the placeholder prop to set a placeholder text.

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

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.

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

Disabled

Use the disabled prop to disable the Select.

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

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.

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

Padded

Use the padded prop to remove the padding of the Select.

<template>
  <USelect
    :padded="false"
    placeholder="Search..."
    :options="['United States', 'Canada', 'Mexico']"
    variant="none"
    class="w-full"
  />
</template>

Slots

leading

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

<template>
  <USelect
    :options="['United States', 'Canada', 'Mexico']"
    placeholder="Search..."
  >
    <template #leading>
      <UIcon name="i-heroicons-flag" class="w-5 h-5" />
    </template>
  </USelect>
</template>

trailing

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

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

Props

Prop	Type	Default	Description
name	string	null
size	SelectSize	"md"	Size of the select
color	string	config.default.color	Color of the select
icon	string	null	Leading icon
ui	object	{}	UI configuration
id	string	null
modelValue	string | number | object	""	Value of the select
options	unknown[]	[]	Options for the select
variant	SelectVariant	config.default.variant	Variant of the select
placeholder	string	null	Placeholder text
loadingIcon	string	config.default.loadingIcon	Loading icon
leadingIcon	string	null	Leading icon
trailingIcon	string	config.default.trailingIcon	Trailing icon
optionAttribute	string	"label"	Attribute to use for option label
valueAttribute	string	"value"	Attribute to use for option value
selectClass	string	null	Additional class for the select
required	boolean	false
disabled	boolean	false	Disable the select
leading	boolean	false
trailing	boolean	false
loading	boolean	false	Show loading state
padded	boolean	true	Add padding to the select

Config

{
  wrapper: 'relative',
  base: 'relative block w-full disabled:cursor-not-allowed disabled:opacity-75 focus:outline-none border-0',
  form: 'form-select',
  rounded: 'rounded-md',
  placeholder: 'text-gray-400 dark:text-gray-500',
  file: {
    base: 'file:mr-1.5 file:font-medium file:text-gray-500 dark:file:text-gray-400 file:bg-transparent file:border-0 file:p-0 file:outline-none'
  },
  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'
  },
  // ... additional configuration details
}