Select
Search for and choose one or more options. Enter selects an option without also submitting the form.
<script setup lang="ts">import { ref } from 'vue'import { UiField, UiSelect } from 'grani' const currencies = [ { value: 'gbp', label: 'British pound' }, { value: 'usd', label: 'US dollar' }, { value: 'eur', label: 'Euro' }, { value: 'pln', label: 'Polish zloty' },] const grouped = [ { label: 'Europe', options: [ { value: 'eur', label: 'Euro' }, { value: 'pln', label: 'Polish zloty' }, ], }, { label: 'Americas', options: [ { value: 'usd', label: 'US dollar' }, { value: 'cad', label: 'Canadian dollar' }, ], },] const plans = [ { value: 'free', label: 'Free', description: 'One project, community support' }, { value: 'team', label: 'Team', description: 'Up to 10 seats' }, { value: 'enterprise', label: 'Enterprise', description: 'Talk to sales', disabled: true },] const currency = ref(null) const region = ref('pln') const plan = ref('team')</script> <template> <div class="flex w-64 max-w-full flex-col gap-6"> <UiField label="Currency"> <UiSelect v-model="currency" :items="currencies" placeholder="Currency" clearable /> </UiField> <UiField label="Region currency"> <UiSelect v-model="region" :items="grouped" /> </UiField> <UiField label="Plan"> <UiSelect v-model="plan" :items="plans" /> </UiField> </div></template>
Also called dropdown, combobox, autocomplete, searchable select.
Usage
<UiSelect v-model="value" /> With GraniResolver in the Vite config, a template needs no import: set it up once.
API
| Name · type | Default | Description |
|---|---|---|
| Value | ||
| modelValue*SelectValue | SelectValue[] | null | The selected value (v-model): null when nothing is selected; with multiple, the picked values in the order they were picked, [] when none is. | |
| Data | ||
| itemsSelectItem[]= [] | [] | Options or groups of options with labels. With fetcher they are the known labels: a prefilled value shows its label before the server answers. |
| fetcher((query: string) => Promise<SelectItem[]>) | Asks a server for the options: called with the filter text on open and as it is typed (250 ms after the last key); a late answer to an older query is dropped. Implies searchable. | |
| State | ||
| loadingboolean= false | false | The options the app passes in items are on their way: with none yet, rows in their shape; with options in view, they stay, dimmed. A fetcher says this by itself. |
| Behavior | ||
| searchableboolean= false | false | Adds a filter to the option list. Typing narrows options by label. |
| clearableboolean= false | false | Adds a button that resets the value to null, or to [] with multiple; never shown on a required field. |
| tagsboolean= false | false | With multiple: every pick as a tag with a cross below the field, the trigger counting them. Without it the picks are listed in the trigger, which fits a narrow place such as a toolbar. |
| multipleboolean= false | false | Several values: check marks in the rows, an array in the model, the list stays open after a pick. |
| Look | ||
| placeholderstring | Shown when nothing is selected. | |
| sizexs | sm | md | Step of the control ladder. Unset, the app's size (createGrani({ size })), sm by default. | |
| tagSizesm | md= "md" | "md" | Size of the tags, as a UiBadge's. |
| Form and access | ||
| namestring | Native name for forms. The value is submitted through a hidden input. | |
| idstring | Own id when standalone. Inside UiField, the field's id takes precedence. | |
| disabledboolean= false | false | Prevents opening and clearing. |
| invalidboolean= false | false | Marks the control as invalid. Shows the invalid border and focus ring. Inside UiField, the error state sets this automatically. |
| ariaLabelstring | Accessible name when there is no visible label. | |
| requiredboolean= false | false | Standalone only: empty is an error, said to a reader, and no cross. Inside UiField the field's required says so. |
Attributes: class and style stay on the outer element; the rest (native attributes, aria-*, data-testid) reach the control inside it.
When to use another component
| When you need | Take |
|---|---|
| A few answers in view | Radio group |
| Several answers in view | Checkbox in a Field group |
| A time of day | Time picker |
| A day | Date picker |
| Commands | Menu |
| A list that adds what is typed | List field |