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"
name="select"
: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"
name="select"
:options="['United States', 'Canada', 'Mexico']"
/>
Gray
<USelect
color="gray"
variant="outline"
name="select"
:options="['United States', 'Canada', 'Mexico']"
/>
Size
Use the size prop to change the size of the Select.
<USelect
size="sm"
name="select"
:options="['United States', 'Canada', 'Mexico']"
/>
Placeholder
Use the placeholder prop to set a placeholder text.
<USelect
placeholder="Search..."
name="select"
: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"
name="select"
:options="['United States', 'Canada', 'Mexico']"
placeholder="Search..."
/>
Disabled
Use the disabled prop to disable the Select.
<USelect
disabled
name="select"
: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"
name="select"
:options="['United States', 'Canada', 'Mexico']"
placeholder="Search..."
/>
Slots
leading
Use the #leading slot to set the content of the leading icon.
<USelect
name="select"
: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 name="input" placeholder="Search...">
<template #trailing>
<UIcon name="i-heroicons-arrows-up-down-20-solid" />
</template>
</USelect>
Props
nullconfig.default.colornullnullundefinednull""[]nullconfig.default.variantconfig.default.loadingIconnullconfig.default.trailingIcon"label""value"nullfalsefalsefalsefalsefalsetruePreset
{
"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"
}
}