ComboboxField

Component

Props

Usage

id

Sets the id of the input. The label is linked to it.

 <template>
    <ComboboxField id="field-id" />
</template>
 

• Type: string
• Required: true

label

Sets the label of the field.

 <template>
    <ComboboxField id="field-id" label="Country" />
</template>
 

• Type: string

ariaLabel

Sets the accessible label of the input. It is only used when there is no label.

 <template>
    <ComboboxField id="field-id" ariaLabel="Country" />
</template>
 

• Type: string

helpText

Sets the help text of the field.

 <template>
    <ComboboxField id="field-id" helpText="Start typing to filter the list" />
</template>
 

• Type: string

helpTextPosition

Sets the position of the help text relative to the field. It uses the Position enum.

 <template>
    <ComboboxField id="field-id" helpText="Appears above the field" :helpTextPosition="Position.TOP" />
</template>
 

• Type: Position
• Default: Position.BOTTOM

Options

required

Sets whether the field is required or not. Validation only runs for required fields.

 <template>
    <ComboboxField id="field-id" required />
</template>
 

• Type: boolean
• Default: false

showOptionalLabel

When the field is not required, shows an "(optional)" hint next to the label. Set it to false to hide it.

 <template>
    <ComboboxField id="field-id" label="Country" :showOptionalLabel="false" />
</template>
 

• Type: boolean
• Default: true

optionalLabel

Overrides the "(optional)" hint text for this field, taking priority over the global default.

 <template>
    <ComboboxField id="field-id" label="Country" optionalLabel="(not required)" />
</template>
 

• Type: string

options

Sets the options of the field. The array of options must be of type SelectOption.

 <template>
    <ComboboxField id="field-id" :options="items" />
</template>
<script setup lang="ts">
const items: SelectOption[] = [
    { value: 1, text: 'Option 1' },
    { value: 2, text: 'Option 2' },
    { value: 3, text: 'Option 3' },
]
</script>
 

• Type: SelectOption[]
• Default: []

placeholder

Sets the placeholder text of the input.

 <template>
    <ComboboxField id="field-id" placeholder="Search a country" />
</template>
 

• Type: string
• Default: 'Select an option'

modelValue

Sets the value of the field. Use v-model to bind it. With multiple, the value is an array.

 <template>
    <ComboboxField id="field-id" v-model="selectedValue" :options="items" />
</template>
<script setup lang="ts">
const selectedValue = ref<string | number | (string | number)[] | null>(null)
</script>
 

• Type: string | number | (string | number)[] | null
• Default: null

type

Sets how the options are rendered in the list. It uses the SelectType enum.

 <template>
    <ComboboxField id="field-id" :type="SelectType.ICON" :options="items" />
</template>
 

• Type: SelectType
• Default: SelectType.TEXT

Options

size

Sets the size of the field. It uses the SelectSize enum.

 <template>
    <ComboboxField id="field-id" :size="SelectSize.LG" />
</template>
 

• Type: SelectSize
• Default: SelectSize.MD

Options

activeStyle

Sets the style of the selected option in the list. It uses the SelectActiveStyle enum.

 <template>
    <ComboboxField id="field-id" :activeStyle="SelectActiveStyle.FILL" />
</template>
 

• Type: SelectActiveStyle
• Default: SelectActiveStyle.CHECK

Options

dropdownPosition

Sets the position of the list relative to the input. It uses the Position enum.

 <template>
    <ComboboxField id="field-id" :dropdownPosition="Position.TOP" />
</template>
 

• Type: Position
• Default: Position.BOTTOM

Options

autoFlip

Moves the dropdown to the other side when it does not fit in the window. If it would be cut off at the bottom or the top edge of the screen and there is more room on the other side, it opens there instead. The position is checked when it opens, and dropdownPosition is only the starting point. Set it to false to always keep the position as given.

 <template>
    <ComboboxField v-model="value" id="combobox" :options="options" :autoFlip="false" />
</template>
 

• Type: boolean
• Default: true

noResultsFoundText

Sets the text displayed when no option matches the typed text.

 <template>
    <ComboboxField id="field-id" noResultsFoundText="No countries found" />
</template>
 

• Type: string
• Default: 'No results found'

disabled

Disables the field.

 <template>
    <ComboboxField id="field-id" disabled />
</template>
 

• Type: boolean
• Default: false

readonly

Sets the readonly state. The value is still displayed but the user cannot change it.

 <template>
    <ComboboxField readonly />
</template>
 

• Type: boolean
• Default: false

validator

Sets the validator function for the field. It runs when the value changes, only if the field is required, and its result is emitted through update:error.

 <template>
    <ComboboxField id="field-id" required :validator="validateField" />
</template>
<script setup lang="ts">
const validateField = (value: unknown) => (value ? null : 'This field is required')
</script>
 

• Type: function
• Default: () => null

error (v-model:error)

Sets the error message of the field. This prop is bindable via v-model:error, allowing two-way syncing of the validation state.

 <template>
    <ComboboxField id="field-id" v-model:error="errorMessage" />
</template>
 

• Type: string
• Default: ''

hasSeparator

Adds a separator between options in the list.

 <template>
    <ComboboxField id="field-id" hasSeparator />
</template>
 

• Type: boolean
• Default: false

multiple

Enables multiple selection. The input becomes a search box and modelValue is an array.

 <template>
    <ComboboxField id="field-id" v-model="values" multiple />
</template>
<script setup lang="ts">
const values = ref<(string | number)[]>([])
</script>
 

• Type: boolean
• Default: false

hasBadgeStack

Displays the selected options as removable badges above the input. Only applies with multiple.

 <template>
    <ComboboxField id="field-id" multiple hasBadgeStack />
</template>
 

• Type: boolean
• Default: false

allowDeselect

Allows deselecting the selected option by picking it again. Only applies to single selection.

 <template>
    <ComboboxField id="field-id" allowDeselect />
</template>
 

• Type: boolean
• Default: false

allowCustomValue

Lets the user commit text that is not part of options by pressing Enter or leaving the input. If the text matches the label of an existing option, that option's value is used instead.

 <template>
    <ComboboxField id="field-id" allowCustomValue />
</template>
 

• Type: boolean
• Default: false

clearable

Shows a button to clear the current value or typed text.

 <template>
    <ComboboxField id="field-id" :clearable="false" />
</template>
 

• Type: boolean
• Default: true

filterLocally

Filters options by their label while the user types. Set it to false when the options come from the server and are already filtered by the @search event.

 <template>
    <ComboboxField
        id="field-id"
        :options="results"
        :filterLocally="false"
        :isLoading="isSearching"
        @search="fetchOptions"
    />
</template>
 

• Type: boolean
• Default: true

searchDebounce

Sets the delay, in milliseconds, between the last keystroke and the search event.

 <template>
    <ComboboxField id="field-id" :searchDebounce="500" @search="fetchOptions" />
</template>
 

• Type: number
• Default: 300

isLoading

Shows a spinner in the input and replaces the list with the loading text. Use it while options are being fetched.

 <template>
    <ComboboxField id="field-id" :isLoading="isSearching" />
</template>
 

• Type: boolean
• Default: false

loadingText

Sets the text displayed in the list while isLoading is true.

 <template>
    <ComboboxField id="field-id" isLoading loadingText="Loading options..." />
</template>
 

• Type: string
• Default: 'Loading options...'

selectBoxClass

Allows passing custom classes to the box that wraps the input.

 <template>
    <ComboboxField id="field-id" selectBoxClass="custom-box" />
</template>
 

• Type: string

transparent

Removes the default background from the box, making it transparent.

 <template>
    <ComboboxField id="field-id" transparent />
</template>
 

• Type: boolean
• Default: false

clearSelectionAriaLabel

Sets the accessible label of the clear button. Useful for i18n.

 <template>
    <ComboboxField id="field-id" clearSelectionAriaLabel="Limpiar selección" />
</template>
 

• Type: string
• Default: 'Clear selection'

shouldTeleport

Teleports the list to teleportTo instead of rendering it inside the field. Enable it when the field is inside a container with overflow-hidden or overflow-auto (such as Table), otherwise the list gets clipped.

 <template>
    <ComboboxField id="field-id" shouldTeleport />
</template>
 

• Type: boolean
• Default: false

teleportTo

Sets the teleport target selector used when shouldTeleport is true.

 <template>
    <ComboboxField id="field-id" shouldTeleport teleportTo="body" />
</template>
 

• Type: string
• Default: 'body'

glowColorMode

Draws a glow around the combobox box only. The label and the help text do not glow. It is shown in light mode, dark mode, both or none, and it uses the GlowColorMode enum. It is GlowColorMode.NONE by default, so the field has no glow until you turn it on.

The glow uses the brand color and turns to the error color when the field has an error.

 <template>
    <ComboboxField :glowColorMode="GlowColorMode.DARK" />
</template>
 

• Type: GlowColorMode
• Default: GlowColorMode.NONE (set by the DS config, see Configuration)

Options

glowTrigger

Sets when the glow appears. It uses the GlowTrigger enum and works together with glowColorMode, which decides in which theme the glow shows. It is GlowTrigger.FOCUS by default.

FOCUS shows the glow while the field has focus. On touch screens there is no hover, so with HOVER the glow never shows.

 <template>
    <ComboboxField :glowColorMode="GlowColorMode.BOTH" :glowTrigger="GlowTrigger.FOCUS" />
</template>
 

• Type: GlowTrigger
• Default: GlowTrigger.FOCUS (set by the DS config, see Configuration)

Options

glowType

Sets where the glow is drawn. It uses the GlowType enum and works together with glowColorMode. It is GlowType.INNER by default.

 <template>
    <ComboboxField :glowColorMode="GlowColorMode.BOTH" :glowType="GlowType.INNER" />
</template>
 

• Type: GlowType
• Default: GlowType.INNER (set by the DS config, see Configuration)

Options

glowOpacity

Sets how strong the glow is, from 0 (invisible) to 100 (full color). The default is 40. Values move in steps of 5, so 42 is rounded to 40. It has no effect while glowColorMode is GlowColorMode.NONE.

 <template>
    <ComboboxField :glowColorMode="GlowColorMode.BOTH" :glowOpacity="30" />
</template>
 

• Type: number
• Default: 40 (set by the DS config, see Configuration)

glowSize

Sets how far the glow spreads, in pixels. It is null by default, so each component keeps its own size (for example, buttons follow their size). Values move in steps of 2 from 0 to 64, so 13 is rounded to 14. It has no effect while glowColorMode is GlowColorMode.NONE.

 <template>
    <ComboboxField :glowColorMode="GlowColorMode.BOTH" :glowSize="32" />
</template>
 

• Type: number
• Default: null (set by the DS config, see Configuration)

Accessibility

The field links its label to the input and the input follows the ARIA combobox pattern, with the highlighted option exposed through aria-activedescendant. When there is no visible label, pass ariaLabel. See DropdownCombobox for the keyboard shortcuts.

Emits

Example

 <template>
    <ComboboxField
        id="user"
        label="User"
        v-model="userId"
        :options="results"
        :filterLocally="false"
        :isLoading="isSearching"
        @search="fetchUsers"
    />
</template>
<script setup lang="ts">
const userId = ref<string | number | null>(null)
const results = ref<SelectOption[]>([])
const isSearching = ref(false)

const fetchUsers = async (query: string) => {
    isSearching.value = true
    results.value = await searchUsers(query)
    isSearching.value = false
}
</script>