Bridge UI

Select

Dropdown select with single/multiple value, search, and async data.

Introduction

Select is a custom dropdown built on FormField and Menu—not a native <select> element.

Use Select when you need searchable options, multiple selection, async data, clearable values, or rich option rendering. Use a native <select> when you prefer the platform’s built-in picker (especially on mobile), need maximum simplicity for short static lists, or must submit unmodified HTML form values without JavaScript.

Import

import { Select } from "@bridge-ui/vue/Components/Select";
import { Select } from "@bridge-ui/react/Components/Select";

Basic usage

Pass an options array of objects with label and value keys (customizable via optionLabel and optionValue). For an initial value without binding, use defaultValue in React or default-value in Vue.

Sizes

Control the select size with the size prop. Available sizes: 2xs, xs, sm, md (default), lg, xl, and 2xl.

Rounded

Use the rounded prop to control border radius on both the field and the listbox dropdown panel. Available values: none, xs, sm, md (default), lg, xl, 2xl, 3xl, 4xl, and full.

Multiple

Enable multiple to allow selecting more than one option. Combine with searchable to filter the list.

Searchable

Set searchable to filter options as the user types. Search UI appears automatically when the option count exceeds minItemsForSearch (default 11).

Declarative options

Use SelectOption children (Vue) or the options prop (React) when options are static and defined in markup.

Grouped options

The options prop may mix standalone options and section groups ({ title, options, sticky? }). Search filters within sections and drops empty ones.

Composed list children

Pass ListSection / ListItem as children to build the dropdown list manually. Set value on each ListItem so it registers as a selectable option. When composed children are present, mapped options are not rendered in the listbox.

Async data

Pass asyncData with search and resolve callbacks for remote or debounced option lists. Implies searchable. While a search or resolve is in flight, the dropdown shows an indeterminate progress bar and loadingMessage (default "Loading..."). You can also drive loading yourself with the loading prop, or replace the message with the loading slot.

For Laravel backends, see Laravel + Inertia.

Validation

Set error and errorMessage to show invalid styling and an error message below the field.

Nested customProps

Use customProps.listbox to forward props to the internal Listbox (including nested customProps for Menu, Progress, List, etc.). Owned Select props such as value and options are not overridable through nested customProps.

<Select
  options={options}
  customProps={{
    label: { id: "country-label" },
    listbox: {
      customProps: {
        menu: { rounded: "xl" },
        progress: { size: "sm" },
      },
    },
  }}
/>

Menu, List

Accessibility

Select requires an accessible name from its label (linked via controlId) or an explicit aria-label on the trigger.

  • Helper and error text are linked through aria-describedby.
  • When error is true, the trigger receives aria-invalid="true".
  • The dropdown list uses listbox semantics; keyboard navigation follows WAI-ARIA combobox patterns when searchable is enabled.

Anatomy

Select composes FormField, a trigger (with chips in multiple mode), and a Menu-based options panel:

FormField (root)
├── Header — label, optional corner text, required indicator
├── Container — variant shell
│   └── Trigger — input / chips showing the current selection
├── Options panel — selectable items (supports search, loading, and multiple selection)
└── Footer — description or error message

API

Prop Type Default Description
v-model SelectModel — Two-way binding for the selected value (single or multiple).
default-value SelectModel — Initial value for uncontrolled usage (without v-model).
Prop Type Default Description
value SelectModel — Selected value (single or multiple). Use with onChange for controlled state.
onChange (value: SelectModel) => void — Called when the selection changes.

Select-specific

Prop Type Default Description
options ListboxOptionsInput — Options to display. May include section groups ({ title, options, sticky? }) mixed with flat options.
children ReactNode — Composed dropdown content (ListSection / ListItem with value). Replaces mapped options.
placeholder string — Placeholder when no value is selected.
multiple boolean false Whether multiple values can be selected.
searchable boolean false Whether options can be filtered via the trigger input.
clearable boolean true Whether the value can be cleared.
asyncData SelectAsyncData — Remote data source. Implies searchable.
loading boolean — External or async loading state (OR’d with async in-flight).
loadingMessage string "Loading..." Message shown in the dropdown while loading.
defaultValue SelectModel | null — Initial value when uncontrolled.
optionLabel string "label" Key used to read the label from option objects.
optionValue string "value" Key used to read the value from option objects.
optionDescription string "description" Key used to read the description from option objects.
minItemsForSearch number 11 Minimum option count before search UI is enabled.
emptyMessage string "No options" Message when the filtered list is empty.
hideEmptyMessage boolean false Hides the empty-state message.
flipOptions boolean false Inverts the visual order of options.
maxHeight string "max-h-60" Tailwind max-height class for the dropdown options area.
disableMaxHeight boolean false When true, the dropdown options list is not height-limited.

Events

| Event | Payload | Description | | ———– | ––––––––––– | ——————————————————— | | @clear | — | Called when the value is cleared. | | @close | — | Called when the menu closes. | | @open | — | Called when the menu opens. | | @search | query: string | Called when the search query changes. | | @select | option: SelectOption | Called when an option is selected. | | @deselect | option: SelectOption | Called when an option is deselected (multiple mode). | | @change | value: SelectModel | Called when the value changes (alternative to v-model). |

| Prop | Payload | Description | | ———— | ––––––––––– |

| | onClear | — | Called when the value is cleared. | | onClose | — | Called when the menu closes. | | onOpen | — | Called when the menu opens. | | onSearch | query: string | Called when the search query changes. | | onSelect | option: SelectOption | Called when an option is selected. | | onDeselect | option: SelectOption | Called when an option is deselected (multiple mode). | | onChange | value: SelectModel | Called when the value changes (alternative to the onChange callback prop). |

Slots

Slot Description
chip Custom chip content in multiple mode ({ option }).
option Custom option item content ({ option, selected }).
loading Custom loading content in the dropdown (progress bar still renders above).
empty Custom empty-state content.
beforeOptions Content above the option list.
afterOptions Content below the option list.

Inherited from FormField

Prop Type Default Description
label string — Primary label text above the control.
description string — Helper text below the control (hidden when invalid).
corner string — Secondary label text at the inline end of the header row.
required boolean false Shows a red asterisk on the label.
disabled boolean false Whether the control is disabled.
readonly boolean false Whether the control is read-only.
error boolean false Applies invalid styling and hides description.
errorMessage string — Error message below the control.
showErrorIcon boolean true Shows an error icon when invalid.
hideErrorMessage boolean false Does not reserve space for error messages.
variant FormFieldVariant "outline" Visual variant of the field shell.
color FormFieldColor "primary" Color applied to the field control.
size FormFieldSize "md" Typography and control sizing.
rounded FormFieldRounded "md" Border radius of the field control and the listbox dropdown panel.
start string — Inline-start text inside the field (prefix).
end string — Inline-end text inside the field (suffix).
startIcon IconSource — Icon at the inline start.
endIcon IconSource — Icon at the inline end.
errorIcon IconSource "alert" Icon shown when invalid and showErrorIcon is enabled.
controlId string — Associates labels and helper text with the control. Auto-generated when omitted.
classes FormFieldClasses — Class overrides per part.
customProps SelectCustomProps — FormField parts plus nested listbox, chip, and clearIcon. label accepts Label props (without children).
slots FormFieldSlots — React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end.