Forms
CustomSelect
Styled select / combobox with a positioned listbox: type-ahead, optional search, async loading, groups, custom options and a clear button.
import { CustomSelect, CustomSelectOption, CustomSelectDropdown } from "datui";Playground
<CustomSelect placeholder="Choose a city" selectType="default" status="default" />Examples
Basic
Disabled options, groups and a clear button.
Searchable
searchable filters by label; filterFn customizes it.
Async options
filterFn={false} with onInputChange and fetching for server-side search.
Custom options
renderOption with descriptions and icons.
Accessibility
- The field is an
<input role="combobox">witharia-expanded,aria-controls,aria-haspopup="listbox"andaria-activedescendant; focus never leaves it. - Down/Up open the list and move the highlight (disabled options are skipped), Home/End jump to the ends, Enter or Space selects, Escape closes, Tab closes and moves on.
- Without
searchable, typing letters jumps to the matching option; Backspace/Delete open the list. - Options are
role="option"witharia-selected/aria-disabled; groups arerole="group"labelled by their header. - The empty text is announced in a polite status region;
fetchingsetsaria-busyand shows a labelled spinner. - Clicking outside, blurring or Escape closes the list; Escape does not also close an enclosing dialog.
- With
name, a hidden input submits the value. Passaria-labelor wrap in FormItem for the label.
API
CustomSelect
Styled select / combobox with a positioned listbox: keyboard navigation, type-ahead, optional search, async loading, custom option rendering and a clear button. `ref` points at the combobox input. With `name`, a hidden input carries the value in form submissions.
| 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 | null | |
| 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 | false | 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`. |
| noMaxHeight | boolean | false | Let the dropdown grow to the available viewport height. |
| onChange | ((event: SyntheticEvent<Element, Event>, value: CustomSelectValue | null) => void) | — | Called with the triggering event and the new value (`null` after clearing). |
| 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. |
CustomSelectOption
One `role="option"` row of a select listbox. The owner (CustomSelect, ChipsSelect) handles keys and passes `id`, `focused`, `selected` and click handlers. Mouse down never takes focus away from the combobox input.
| Prop | Type | Default | Description |
|---|---|---|---|
| after | ReactNode | — | Content after the label. A check mark is shown instead while `selected` and `after` is unset. |
| before | ReactNode | — | |
| className | string | — | |
| description | ReactNode | — | Secondary line under the label. |
| disabled | boolean | false | |
| focused | boolean | false | Keyboard / pointer highlight (the combobox's active descendant). |
| hierarchy | number | 0 | Nesting level; each level indents the row. |
| selected | boolean | false | Marks the option as the current value (`aria-selected`, check mark). |
| textNoWrap | boolean | false | Keep the label on one line with an ellipsis. |
CustomSelectDropdown
Positioned, scrollable popup panel used by CustomSelect and ChipsSelect. It has no keyboard handling of its own: put a `role="listbox"` inside and let the owning combobox drive it.
| Prop | Type | Default | Description |
|---|---|---|---|
| targetRef (required) | RefObject<HTMLElement | null> | — | Element the dropdown is attached to (usually the FormField shell). |
| autoWidth | boolean | false | Size to content instead of matching the target width (never narrower than the target). |
| className | string | — | |
| fetching | boolean | false | Shows a spinner instead of the content. |
| fetchingLabel | string | "Loading…" | Accessible label of the spinner. |
| forcePortal | boolean | true | Render into the AppRoot portal layer. `false` renders in place. |
| noMaxHeight | boolean | false | Let the list grow to fit the viewport instead of capping it. |
| offsetDistance | number | 4 | Gap between target and dropdown in px. |
| onPlacementChange | ((placement: CustomSelectDropdownPlacement) => void) | — | Called with the final placement after flipping. |
| placement | CustomSelectDropdownPlacement | bottom-start | Preferred side; flips when there is no room. |
| scrollBoxRef | Ref<HTMLDivElement> | — | Ref to the scrolling box, e.g. to keep the highlighted option in view. |