Display a select field.
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>
Use the color
and variant
props to change the visual style of the Select.
<template>
<USelect
color="white"
variant="outline"
:options="['United States', 'Canada', 'Mexico']"
/>
</template>
<template>
<USelect
color="gray"
variant="outline"
:options="['United States', 'Canada', 'Mexico']"
/>
</template>
Use the size
prop to change the size of the Select.
<template>
<USelect
size="sm"
:options="['United States', 'Canada', 'Mexico']"
/>
</template>
Use the placeholder
prop to set a placeholder text.
<template>
<USelect
placeholder="Search..."
:options="['United States', 'Canada', 'Mexico']"
/>
</template>
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>
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.
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>
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>
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>
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 |
{
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
}