datui
Color scheme

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.

Moscow is unavailable

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"> with aria-expanded, aria-controls, aria-haspopup="listbox" and aria-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" with aria-selected / aria-disabled; groups are role="group" labelled by their header.
  • The empty text is announced in a polite status region; fetching sets aria-busy and 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. Pass aria-label or 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.

PropTypeDefaultDescription
options (required)CustomSelectOptionData[]—
allowClearButtonbooleanfalseShows a clear button while a value is selected.
beforeReactNode—Content before the control, usually an icon.
classNamestring—
clearLabelstringClearAccessible label of the clear button.
defaultValueCustomSelectValuenull
dropdownAutoWidthbooleanfalseSize the dropdown to its content instead of the field width.
dropdownOffsetDistancenumber4Gap between field and dropdown in px.
emptyTextstringNothing foundShown when no option matches.
fetchingbooleanfalseShows a spinner in the field and the dropdown, e.g. while options load.
fetchingLabelstringLoading…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.
listLabelstringOptionsAccessible name of the listbox when the select has no `aria-label`.
noMaxHeightbooleanfalseLet 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"bottomPreferred 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.
selectTypeSelectTypedefault`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.

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.

PropTypeDefaultDescription
afterReactNode—Content after the label. A check mark is shown instead while `selected` and `after` is unset.
beforeReactNode—
classNamestring—
descriptionReactNode—Secondary line under the label.
disabledbooleanfalse
focusedbooleanfalseKeyboard / pointer highlight (the combobox's active descendant).
hierarchynumber0Nesting level; each level indents the row.
selectedbooleanfalseMarks the option as the current value (`aria-selected`, check mark).
textNoWrapbooleanfalseKeep 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.

PropTypeDefaultDescription
targetRef (required)RefObject<HTMLElement | null>—Element the dropdown is attached to (usually the FormField shell).
autoWidthbooleanfalseSize to content instead of matching the target width (never narrower than the target).
classNamestring—
fetchingbooleanfalseShows a spinner instead of the content.
fetchingLabelstring"Loading…"Accessible label of the spinner.
forcePortalbooleantrueRender into the AppRoot portal layer. `false` renders in place.
noMaxHeightbooleanfalseLet the list grow to fit the viewport instead of capping it.
offsetDistancenumber4Gap between target and dropdown in px.
onPlacementChange((placement: CustomSelectDropdownPlacement) => void)—Called with the final placement after flipping.
placementCustomSelectDropdownPlacementbottom-startPreferred side; flips when there is no room.
scrollBoxRefRef<HTMLDivElement>—Ref to the scrolling box, e.g. to keep the highlighted option in view.