YuhuanStudioYunUIDocs
Forms & Inputs

CustomSelect

Fully custom-styled select with optional search, icons, descriptions and keyboard support.

A fully custom-styled dropdown select with optional in-dropdown search, per-option icons and descriptions, and complete keyboard support (arrows, Home/End, Enter, Escape). It's controlled: pass value and onChange, plus an options array. For free-text entry or creatable values see Combobox; for the Radix-based composed parts see Select.

Import

tsx1 line
import { CustomSelect } from "@yuhuanowo/yunui";

Usage

CustomSelect is controlled — wire value and onChange to state:

tsx14 linesScroll horizontally
const [value, setValue] = useState("medium");

<CustomSelect
value={value}
onChange={setValue}
searchable
placeholder="Select a model size"
options={[
{ value: "small", label: "Small", description: "Fast, lower cost" },
{ value: "medium", label: "Medium", description: "Balanced" },
{ value: "large", label: "Large", description: "Highest quality" },
{ value: "xl", label: "Extra Large", description: "Maximum capacity" },
]}
/>

Example

Set searchable to add a filter box inside the dropdown. Each option can carry an icon and a secondary description line.

Searchable select with descriptions

By default searchable filters the given options client-side. Pass onSearch to drive results from a backend instead: it fires (debounced by searchDebounceMs, default 250) with the current query, and you replace options with the fetched results. Pair it with loading to surface the in-flight fetch.

tsx15 lines
const [options, setOptions] = useState<CustomSelectOption[]>([]);
const [loading, setLoading] = useState(false);

<CustomSelect
searchable
value={value}
onChange={setValue}
options={options}
loading={loading}
onSearch={async (query) => {
setLoading(true);
setOptions(await searchModels(query));
setLoading(false);
}}
/>

Infinite scroll

For long or paged result sets, pass onLoadMore + hasMore. onLoadMore fires when the list is scrolled near its end (and no fetch is in flight); append the next page to options. It's independent of onSearch — use either or both.

tsx7 lines
<CustomSelect
value={value}
onChange={setValue}
options={options}
hasMore={hasMore}
onLoadMore={() => loadNextPage()}
/>

Props

PropTypeDefaultDescription
classNamestring—
disabledbooleanfalseDisable interaction and dim the control.
hasMorebooleanfalseWhether more options can be loaded; gates `onLoadMore` and the footer spinner.
loadingbooleanfalseIn remote mode, show a loading indicator while results are being fetched.
onChange*(value: string) => void—Called with the chosen option's value.
onLoadMore(() => void)—Infinite scroll. Called when the options list is scrolled near its end and `hasMore` is true (and no fetch is in flight). The host appends the next page to `options`. Independent of `onSearch` — use either or both.
onSearch((query: string) => void)—Server-backed search. When provided, the component switches to remote mode: it stops filtering `options` locally (the host owns filtering) and instead calls `onSearch` — debounced by `searchDebounceMs` — with the current query so the host can fetch matching options. A search box is shown even without `searchable`. Pair with `loading` to surface the in-flight fetch.
options*SelectOption[]—The selectable options.
placeholderstring—Placeholder shown when nothing is selected (falls back to i18n default).
searchablebooleanfalseShow an in-dropdown search box that filters options by label/value.
searchDebounceMsnumber250Debounce (ms) before `onSearch` fires.
value*string—Currently selected value (controlled).

On this page