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.

React
React

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.

Client-side asyncData with search and resolve callbacks.

Client-side asyncData with search and resolve callbacks.

Overlay

Use the overlay prop to choose the picker shell: auto (default), menu, modal, or drawer. auto uses menu on desktop and a bottom drawer on mobile. When unset, showFooter defaults to true for modal / drawer overlays (false for menu). Apply commits and closes; Cancel discards and closes.

A custom footer slot replaces Cancel / Apply on the nested listbox. Call apply() to commit the draft and close, or cancel() to discard and close.

Custom footer replaces Cancel / Apply.

Custom footer replaces Cancel / Apply.

Validation

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

Please select a valid country.

Please select a valid country.

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 an overlay-based options panel (auto by default: menu on desktop, bottom drawer on mobile):

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.
overlay FieldOverlayMode "auto" Overlay shell: menu, modal, drawer, or auto.
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.
showFooter boolean false (true for modal/drawer when unset) Shows Cancel / Apply on the nested listbox. Selection stays draft until Apply.
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
@apply — Emitted when Apply is pressed on the listbox footer (showFooter).
@cancel — Emitted when Cancel is pressed on the listbox footer (showFooter).
@clear — Emitted when the value is cleared.
@close — Emitted when the menu closes.
@open — Emitted when the menu opens.
@search query: string Emitted when the search query changes.
@select option: SelectOption Emitted when an option is selected.
@deselect option: SelectOption Emitted when an option is deselected (multiple mode).
@change value: SelectModel Emitted when the value changes (alternative to v-model).
Prop Payload Description
onApply — Called when Apply is pressed on the listbox footer (showFooter).
onCancel — Called when Cancel is pressed on the listbox footer (showFooter).
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.

Slots

Slot Description
chip Custom chip content in multiple mode ({ option }).
option Custom option item content ({ option, selected }).
footer Custom footer. Replaces Cancel / Apply. Call apply() to commit and close, or cancel() to discard.
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, clearIcon, and overlay shells (menu, modal, drawer). label accepts Label props (without children).
slots FormFieldSlots — React slots. Vue: #label, #corner, default, #description, #errorMessage, #start, #end.