datui
Color scheme

Forms

Select

Adaptive select driven by an options array: CustomSelect with a mouse, the platform picker (NativeSelect) on touch devices.

import { Select } from "datui";

Playground

<Select placeholder="Choose…" selectType="default" />

Examples

Options

Forcing an implementation

native overrides pointer detection.

Accessibility

  • With a fine pointer it renders CustomSelect (combobox + listbox); on coarse pointers a native <select>.
  • Both implementations take their label from FormItem or aria-label and report aria-invalid from status.
  • onChange always receives the value as a string ("" after clearing), whichever implementation renders.

API

Select

Adaptive select driven by an `options` array: CustomSelect with a mouse, the platform picker (NativeSelect) on touch devices. Value, placeholder, status, name and labelling behave the same in both. DOM event props and CustomSelect-only features (search, custom options, clear button) apply to the custom implementation. `ref` points at the custom combobox input or the native `<select>`.

PropTypeDefaultDescription
options (required)CustomSelectOptionData[]—
allowClearButtonbooleanfalseShows a clear button while a value is selected.
beforeReactNode—Content before the control, usually an icon.
classNamestring—
clearLabelstring"Clear"Accessible label of the clear button.
defaultValueCustomSelectValue—
dropdownAutoWidthbooleanfalseSize the dropdown to its content instead of the field width.
dropdownOffsetDistancenumber4Gap between field and dropdown in px.
emptyTextstring"Nothing found"Shown when no option matches.
fetchingboolean—Shows a spinner in the field and the dropdown, e.g. while options load.
fetchingLabelstring"Loading…"Accessible loading label.
filterFnfalse | ((query: string, option: CustomSelectOptionData) => boolean)—Custom filter, or `false` to show options as given (e.g. results filtered on the server).
forcePortalbooleantruePortal the dropdown into the AppRoot layer.
iconReactNodechevronTrailing icon.
listLabelstring"Options"Accessible name of the listbox when the select has no `aria-label`.
nativeboolean—`true` always renders NativeSelect, `false` always CustomSelect. Unset: NativeSelect on coarse-pointer (touch) devices, CustomSelect with a fine pointer.
noMaxHeightbooleanfalseLet the dropdown grow to the available viewport height.
onChange((event: SyntheticEvent<Element, Event>, value: string) => void)—Called with the event and the new value as a string (`""` after clearing), whichever implementation renders.
onClose(() => void)—
onInputChange((event: ChangeEvent<HTMLInputElement, Element>, query: string) => void)—Search text changes (only with `searchable`).
onOpen(() => void)—
popupDirection"top" | "bottom""bottom"Preferred dropdown side; it flips when there is no room.
renderOption((props: CustomSelectOptionProps, option: CustomSelectOptionData) => ReactNode)—Custom option row. Spread the given props onto `CustomSelectOption` (or an element with the same role/id).
searchablebooleanfalseLets the user type to filter the options.
selectTypeSelectType"default"`default` bordered field, `plain` borderless, `accent` borderless accent text.
slotProps{ root?: (FormFieldProps & { ref?: Ref<HTMLDivElement>; }); } | undefined—Props for the FormField shell. `className` and `style` go to the shell too.
statusFormFieldStatus"default"Visual validation state. Pair `error` with `aria-invalid` on the control (FormItem does this).
valueCustomSelectValue—Selected value; `null` means nothing selected.