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-labeland reportaria-invalidfromstatus. onChangealways 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>`.
| Prop | Type | Default | Description |
|---|---|---|---|
| options (required) | CustomSelectOptionData[] | — | |
| allowClearButton | boolean | false | Shows a clear button while a value is selected. |
| before | ReactNode | — | Content before the control, usually an icon. |
| className | string | — | |
| clearLabel | string | "Clear" | Accessible label of the clear button. |
| defaultValue | CustomSelectValue | — | |
| dropdownAutoWidth | boolean | false | Size the dropdown to its content instead of the field width. |
| dropdownOffsetDistance | number | 4 | Gap between field and dropdown in px. |
| emptyText | string | "Nothing found" | Shown when no option matches. |
| fetching | boolean | — | Shows a spinner in the field and the dropdown, e.g. while options load. |
| fetchingLabel | string | "Loading…" | Accessible loading label. |
| filterFn | false | ((query: string, option: CustomSelectOptionData) => boolean) | — | Custom filter, or `false` to show options as given (e.g. results filtered on the server). |
| forcePortal | boolean | true | Portal the dropdown into the AppRoot layer. |
| icon | ReactNode | chevron | Trailing icon. |
| listLabel | string | "Options" | Accessible name of the listbox when the select has no `aria-label`. |
| native | boolean | — | `true` always renders NativeSelect, `false` always CustomSelect. Unset: NativeSelect on coarse-pointer (touch) devices, CustomSelect with a fine pointer. |
| noMaxHeight | boolean | false | Let 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). |
| searchable | boolean | false | Lets the user type to filter the options. |
| selectType | SelectType | "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. |
| status | FormFieldStatus | "default" | Visual validation state. Pair `error` with `aria-invalid` on the control (FormItem does this). |
| value | CustomSelectValue | — | Selected value; `null` means nothing selected. |