Components
Select
A single-value combobox with search, groups, descriptions, and collision-aware positioning.
Select is a single-value combobox built on Base UI's Select and Combobox primitives. Non-searchable
use renders a select button; searchable renders a filterable combobox input. Base UI owns
positioning, collision handling, dismissal, highlight, and listbox semantics.
Import it from @orkest/ui/client because the menu uses client-side state.
Live preview#
import { Select } from '@orkest/ui/client';
const fruits = [
{ value: 'apple', label: 'Apple' },
{ value: 'banana', label: 'Banana' },
{ value: 'cherry', label: 'Cherry' },
{ value: 'grape', label: 'Grape' },
{ value: 'mango', label: 'Mango' },
];
export function Example() {
return <Select aria-label="Fruit" options={fruits} defaultValue="apple" clearable />;
}Searchable#
Set searchable to turn the trigger into a text input. Typing filters option labels with a
case-insensitive match; clear the query to restore the full list. Pass filterOption to replace the
default matcher, or onSearchChange together with loading for async search.
import { Select } from '@orkest/ui/client';
const languages = [
{ value: 'javascript', label: 'JavaScript' },
{ value: 'typescript', label: 'TypeScript' },
{ value: 'python', label: 'Python' },
{ value: 'go', label: 'Go' },
{ value: 'rust', label: 'Rust' },
{ value: 'swift', label: 'Swift' },
];
export function Example() {
return (
<Select
aria-label="Language"
options={languages}
searchable
searchPlaceholder="Search languages"
placeholder="Choose a language"
/>
);
}For async search, return true from filterOption when the server already filtered the options:
<Select
searchable
options={results}
loading={loading}
filterOption={() => true}
onSearchChange={(query) => fetchOptions(query)}
/>Groups, descriptions, and icons#
Options can be grouped and extended with description, icon, and disabled:
interface SelectOption {
value: string;
label: string;
description?: ReactNode;
icon?: LucideIcon;
disabled?: boolean;
}
interface SelectOptionGroup {
label: string;
options: SelectOption[];
}Groups render role="group" with the group label as the accessible name. Descriptions are visible
secondary text and are included in the option's accessible name. icon renders a decorative leading
icon; the trailing check is the selection indicator and is rendered automatically.
import { Briefcase, Code, Layers, Megaphone, Palette, Server } from 'lucide-react';
import { Select } from '@orkest/ui/client';
const teams = [
{
label: 'Product',
options: [
{
value: 'design',
label: 'Design',
description: 'Product design and research',
icon: Palette,
},
{
value: 'product',
label: 'Product',
description: 'Planning and strategy',
icon: Briefcase,
},
{
value: 'marketing',
label: 'Marketing',
description: 'Campaigns and brand',
icon: Megaphone,
},
],
},
{
label: 'Engineering',
options: [
{ value: 'frontend', label: 'Frontend', description: 'Web interfaces', icon: Code },
{ value: 'backend', label: 'Backend', description: 'APIs and services', icon: Server },
{
value: 'platform',
label: 'Platform',
description: 'Infrastructure and tooling',
icon: Layers,
},
],
},
];
export function Example() {
return <Select aria-label="Team" options={teams} defaultValue="design" clearable />;
}Sizes#
Sizes follow the existing Input height, radius, and padding tokens.
import { Stack } from '@orkest/ui';
import { Select } from '@orkest/ui/client';
const priorities = [
{ value: 'low', label: 'Low' },
{ value: 'medium', label: 'Medium' },
{ value: 'high', label: 'High' },
];
export function Example() {
return (
<Stack gap={3}>
<Select aria-label="Small priority" size="sm" options={priorities} defaultValue="medium" />
<Select aria-label="Medium priority" size="md" options={priorities} defaultValue="medium" />
<Select aria-label="Large priority" size="lg" options={priorities} defaultValue="medium" />
</Stack>
);
}States#
disabled blocks interaction, invalid applies the danger border and aria-invalid, and
clearable adds a clear action while a value is selected.
import { Stack } from '@orkest/ui';
import { Select } from '@orkest/ui/client';
const statuses = [
{ value: 'active', label: 'Active' },
{ value: 'paused', label: 'Paused' },
{ value: 'archived', label: 'Archived' },
];
export function Example() {
return (
<Stack gap={3}>
<Select aria-label="Disabled status" options={statuses} defaultValue="active" disabled />
<Select aria-label="Invalid status" options={statuses} placeholder="Choose a status" invalid />
<Select aria-label="Clearable status" options={statuses} defaultValue="paused" clearable />
</Stack>
);
}Loading and empty states#
loading renders a status row and marks the listbox busy. When filtering returns nothing, the menu
shows emptyMessage.
import { Select } from '@orkest/ui/client';
export function Example() {
return (
<Select
aria-label="Searching languages"
options={[]}
searchable
loading
searchPlaceholder="Search languages"
emptyMessage="No languages matched"
/>
);
}Props#
| Prop | Type | Default |
|---|---|---|
options | Array<SelectOption | SelectOptionGroup> | — |
| Options and option groups rendered in the listbox. | ||
value | string | — |
| Controlled selected value. | ||
defaultValue | string | — |
| Initial value for uncontrolled usage. | ||
onChange | (value: string | undefined, option?: SelectOption) => void | — |
| Called with the next value, or undefined when cleared. | ||
placeholder | string | 'Select an option' |
| Text shown when nothing is selected. | ||
searchable | boolean | false |
| Enables the search input and local filtering. | ||
searchPlaceholder | string | 'Search…' |
| Placeholder for the search input while the menu is open. | ||
onSearchChange | (query: string) => void | — |
| Called when the query changes, including reset on close. | ||
filterOption | (option: SelectOption, query: string) => boolean | — |
| Replaces the default case-insensitive label filter. | ||
emptyMessage | ReactNode | 'No options' |
| Content shown when no options match. | ||
loading | boolean | false |
| Shows a loading row and sets aria-busy on the listbox. | ||
clearable | boolean | false |
| Shows a clear action while a value is selected. | ||
clearLabel | string | 'Clear selection' |
| Accessible name for the clear action. | ||
disabled | boolean | false |
| Disables the entire control. | ||
required | boolean | false |
| Marks the field required and forwards it to Base UI hidden form input. | ||
invalid | boolean | false |
| Applies the danger border and aria-invalid. | ||
size | 'sm' | 'md' | 'lg' | 'md' |
| Control size using Input height and radius tokens. | ||
name | string | — |
| Form field name for the hidden input. | ||
id | string | — |
| Id applied to the combobox element. | ||
className | string | — |
| Class name applied to the root element. | ||
leftIcon | LucideIcon | — |
| Decorative icon rendered before the value. | ||
aria-label / aria-labelledby | string | — |
| Accessible name for the combobox and listbox. | ||
aria-describedby / aria-errormessage | string | — |
| Connects help text and validation messages. | ||
Accessibility#
- Base UI renders the combobox and listbox semantics, including
role="option",aria-expanded,aria-selected, andaria-disabled. Option highlighting is managed by the primitive. - The popup uses Base UI collision handling and is portaled inside the component root, so scoped themes still apply.
- Outside pointer interactions, Escape, Tab, and selecting an option close the popup and restore focus.
- Disabled options are skipped by keyboard navigation.
requiredis forwarded to Base UI's hidden form input and participates in native form validation for single selection.nameidentifies the field.- Associate a visible label with
idandhtmlFor, or usearia-label/aria-labelledby.
| Key | Behavior |
|---|---|
Enter | Opens the menu or selects the highlighted option |
Space | Opens the menu; inserts a space in searchable mode |
ArrowDown / ArrowUp | Opens the menu or moves the highlight |
Escape | Closes the menu and restores focus |
Tab | Closes the menu and moves focus |
| Letter keys | Typeahead; filters when searchable |
Related#
- MultiSelect for multiple values with tags.
- Input for the shared field styling.
- Label for external labels.