Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Forms

Select

A select-only combobox with keyboard navigation and typeahead.

Last changed in version 0.14.2: Improve keyboard navigation, action feedback, and selected colors across Vue components.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add select

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Select from './components/ui/select/Select.vue'
import SelectContent from './components/ui/select/SelectContent.vue'
import SelectOption from './components/ui/select/SelectOption.vue'
import SelectTrigger from './components/ui/select/SelectTrigger.vue'
import SelectValue from './components/ui/select/SelectValue.vue'

const country = ref<string>()
</script>

<template>
  <label for="country">Country</label>
  <Select id="country" v-model="country">
    <SelectTrigger><SelectValue placeholder="Choose a country" /></SelectTrigger>
    <SelectContent>
      <SelectOption value="LU">Luxembourg</SelectOption>
      <SelectOption value="BE">Belgium</SelectOption>
    </SelectContent>
  </Select>
</template>

Arrow keys move through options without changing the value. Select with Enter or Space; Escape and Tab close without selecting. Give the field a label. With clearable enabled, the clear button replaces the chevron.

When to use it

Known category

Select one value from a short fixed list with keyboard typeahead.

Optional filter

Allow the user to clear an already selected filter.

More examples

Support priority

Compose the trigger and options from the public children.

Support priority
<script setup lang="ts">
import { ref } from 'vue'
import Select from './components/ui/select/Select.vue'
import SelectContent from './components/ui/select/SelectContent.vue'
import SelectOption from './components/ui/select/SelectOption.vue'
import SelectTrigger from './components/ui/select/SelectTrigger.vue'
import SelectValue from './components/ui/select/SelectValue.vue'

const priority = ref<string>()
</script>
<template>
  <label for="priority">Priority</label>
  <Select id="priority" v-model="priority" name="priority" required>
    <SelectTrigger><SelectValue placeholder="Choose priority" /></SelectTrigger>
    <SelectContent>
      <SelectOption value="normal">Normal</SelectOption>
      <SelectOption value="urgent">Urgent</SelectOption>
    </SelectContent>
  </Select>
</template>

Clearable status filter

The clear action needs its own accessible name.

Clearable status filter
<script setup lang="ts">
import { ref } from 'vue'
import Select from './components/ui/select/Select.vue'

const status = ref<string>()
const options = [
  { label: 'Open', value: 'open' },
  { label: 'Closed', value: 'closed' },
]
</script>
<template>
  <label for="status">Status</label>
  <Select
    id="status"
    v-model="status"
    :options="options"
    placeholder="Any status"
    clearable
    clear-label="Clear status"
  />
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Select

Complete API for Select
NameType or signatureDefaultWhat it does
modelValuemodelT | undefinedNot setCurrent value. Use v-model to keep it in sync with your page.
defaultValuepropT | undefinedNot setStarting value when the parent does not control the value.
openmodelboolean | undefinedNot setCurrent open state. Use v-model:open to keep it in sync with your page.
defaultOpenpropboolean | undefinedNot setStarting open state when the parent does not control open.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
requiredpropboolean | undefinedNot setAsk the browser to require a value before form submission.
invalidpropboolean | undefinedNot setShow the invalid state; also provide a visible error message.
namepropstring | undefinedNot setName used when this control submits a value with a form.
formpropstring | undefinedNot setAssociate the control with a form by its ID.
idpropstring | undefinedNot setGive the control an ID so a label or description can refer to it.
sizepropControlSize | undefined"md"Choose the visual size. Medium is the usual default where available.
gappropnumber | undefined12Space in pixels between the trigger and floating content.
byprop((a: T, b: T) => boolean) | undefinedNot setCompare two values when identity is not enough, such as object options.
serializeprop((value: T) => string) | undefinedNot setTurn a selected value into the string submitted with a form.
optionspropreadonly SelectOption<T>[] | undefinedNot setCompatibility convenience. Compound SelectOption children remain the source of truth.
messagespropSelectMessages | undefinedNot setSupply the text this component displays for its built-in actions and states.
placeholderpropstring | undefinedNot setHint shown when no value has been entered or selected.
clearablepropboolean | undefinedNot setShow an action for clearing the selected value.
clearLabelpropstring | undefinedNot setAccessible name for the compatibility clear button, if messages.clearSelection is absent.
changeevent[value: T | undefined]—Emitted after this value or state changes.
update:modelValueevent[value: T | undefined]—Requests a new model value from the parent.
update:openevent[open: boolean]—Requests a new open value from the parent.
openChangeevent[open: boolean]—Emitted after this value or state changes.
defaultslot(() => unknown) | undefinedOptionalContent shown inside Select.
prefixslot(() => unknown) | undefinedOptionalContent shown before the main label or value.
suffixslot(() => unknown) | undefinedOptionalContent shown after the main label or value.
errorslot((props: { message: string; messages: string[]; }) => unknown) | undefinedOptionalContent for the error area of Select.
elementexposedHTMLButtonElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
openexposed(last?: boolean) => Promise<void>—Open this component from application code.
closeexposed(restoreFocus?: boolean) => void—Close this component from application code.

SelectContent

Complete API for SelectContent
NameType or signatureDefaultWhat it does
widthpropstring | number | undefined"trigger"Choose the width of this content.
defaultslot() => unknownRequiredContent shown inside SelectContent.

SelectGroup

Complete API for SelectGroup
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside SelectGroup.

SelectLabel

Complete API for SelectLabel
NameType or signatureDefaultWhat it does
defaultslot() => unknownRequiredContent shown inside SelectLabel.

SelectOption

Complete API for SelectOption
NameType or signatureDefaultWhat it does
valuepropTRequiredValue represented by this control or option.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
textValuepropstring | undefinedNot setPlain text used for search, typeahead, or an accessible label.
labelpropstring | undefinedNot setVisible or accessible name for this item.
defaultslot() => unknownRequiredContent shown inside SelectOption.
indicatorslot(() => unknown) | undefinedOptionalContent for the indicator area of SelectOption.

SelectSeparator

Complete API for SelectSeparator
NameType or signatureDefaultWhat it does

SelectTrigger

Complete API for SelectTrigger
NameType or signatureDefaultWhat it does
sizepropControlSize | undefinedNot setChoose the visual size. Medium is the usual default where available.
showIndicatorpropboolean | undefinedtrueHide the default chevron when supplying a different trailing action.
defaultslot() => unknownRequiredContent shown inside SelectTrigger.

SelectValue

Complete API for SelectValue
NameType or signatureDefaultWhat it does
placeholderpropstring | undefinedNot setHint shown when no value has been entered or selected.
defaultslot((props: { value: unknown; option: unknown; }) => unknown) | undefinedOptionalContent shown inside SelectValue.
placeholderslot(() => unknown) | undefinedOptionalContent for the placeholder area of SelectValue.
Public type definitions
Public types
// packages/frameworks/vue/components/select/types.ts
// ------- IMPORTS -------

import type { ControlSize, SelectOption as LegacySelectOption } from '@getweini/vue/types'

// ------- TYPES -------

export type SelectValueType = string | number

export interface SelectMessages {
  listboxLabel: string
  empty: string
  clearSelection: string
}

export interface SelectProps<T = SelectValueType> {
  modelValue?: T
  defaultValue?: T
  open?: boolean
  defaultOpen?: boolean
  disabled?: boolean
  required?: boolean
  invalid?: boolean
  name?: string
  form?: string
  id?: string
  size?: ControlSize
  gap?: number
  by?: (a: T, b: T) => boolean
  serialize?: (value: T) => string
  /** Compatibility convenience. Compound SelectOption children remain the source of truth. */
  options?: readonly LegacySelectOption<T>[]
  messages?: SelectMessages
  placeholder?: string
  clearable?: boolean
  /** Accessible name for the compatibility clear button, if messages.clearSelection is absent. */
  clearLabel?: string
}

export interface SelectTriggerProps {
  size?: ControlSize
  /** Hide the default chevron when supplying a different trailing action. */
  showIndicator?: boolean
}

export interface SelectValueProps {
  placeholder?: string
}

export interface SelectContentProps {
  width?: 'trigger' | string | number
}

export interface SelectOptionProps<T = SelectValueType> {
  value: T
  disabled?: boolean
  textValue?: string
  label?: string
}

// ------- EXPORTS -------

export type SelectOption<T = unknown> = LegacySelectOption<T>


// packages/frameworks/vue/dist/types/index.d.ts
export type { ButtonOptions, ButtonProps } from './button';
export type ControlSize = 'sm' | 'md' | 'lg';
export interface SelectOption<T = unknown> {
    label: string;
    value: T;
    disabled?: boolean;
}
/** Application-owned copy. Bind translated strings reactively when the locale changes. */
export interface ListboxMessages {
    /** Popup name when no aria-label or aria-labelledby is supplied. */
    listboxLabel: string;
    empty: string;
    clearSelection: string;
}
export interface ListboxProps<T> {
    options: readonly SelectOption<T>[];
    messages: ListboxMessages;
    id?: string;
    disabled?: boolean;
    required?: boolean;
    invalid?: boolean;
    name?: string;
    form?: string;
    placeholder?: string;
    size?: ControlSize;
    clearable?: boolean;
    gap?: number;
    /** Supply stable equality for object values. Values must be unique. */
    by?: (a: T, b: T) => boolean;
    /** Required for meaningful form submission of object values. */
    serialize?: (value: T) => string;
}


// packages/frameworks/vue/dist/types/button.d.ts
import type { Component } from 'vue';
/** Options shared by button implementations across frameworks. */
export interface ButtonOptions<Variant extends string = string, Size extends string = string> {
    variant?: Variant;
    size?: Size;
    disabled?: boolean;
    loading?: boolean;
    type?: 'button' | 'submit' | 'reset';
}
/** Vue-specific target options extend the reusable button contract. */
export interface ButtonProps<Variant extends string = 'default' | 'secondary' | 'outline' | 'ghost' | 'destructive', Size extends string = 'sm' | 'md' | 'lg'> extends ButtonOptions<Variant, Size> {
    as?: 'button' | 'a' | Component;
    asChild?: boolean;
}

Implementation notes

  • Object values use Object.is equality by default. Supply by for custom equality and serialize for meaningful object form values.
  • The options prop is a compatibility shortcut; compound children support grouped and rich content.
  • The model is committed on selection; moving the active option with arrows does not update it.

Accessibility and localization

  • Name the field with an associated label. Supply textValue for options with rich visual markup so typeahead and the closed value remain meaningful.

Source contract and editing guidance