forms / stable

Select

Single-choice popover. Pass items with id/label or nest SelectItem in SelectSection; control selectedKey with onSelectionChange, or initialize defaultSelectedKey.

LIVE PREVIEW

Loading preview…

When to use

Choose among more than five options or save space. Supply label or aria-label; items support leading, description and grouped sections.

Consider an alternative

2–5 options that should all be visible — use RadioGroup or segmented Tabs.
Long or searchable lists — use ComboBox.
Actions — use Menu.

Import

import { Select } from '@revido-llc/kit';

Keyboard interaction

Enter / Space / ↓ — open
↑ / ↓ — move
Type — jump to option
Escape — close

Props

Props documented by the Kit. Refer to the TypeScript types for the complete interface, including inherited props.


children	ReactNode	—	Hand-written `SelectItem` / `SelectSection` children (when not using `items`).
className	string	—	Classes for the root (label + trigger + help).
defaultSelectedKey	Key	—	The initially selected option id (uncontrolled).
description	ReactNode	—	One short sentence of help under the control.
errorMessage	string \| ((validation: ValidationResult) => string)	—	Error text shown while the field is invalid (or a function of the validation result).
items	SelectItems	—	Options and/or sections. Omit to pass `SelectItem` children instead.
label	ReactNode	—	Visible label. Omit only when an `aria-label` names the field.
onSelectionChange	((key: Key) => void)	—	Called with the newly selected id.
placeholder	string	"Select…"	Text shown while nothing is selected.
selectedKey	Key	—	The selected option id (controlled). `null` = nothing selected.
size	FieldSize	"md"	`md` 32px (default) or `compact` 28px for tables, filters and toolbars.
triggerClassName	string	—	Classes for the trigger button.
autoComplete	string	—	Describes the type of autocomplete functionality the input should provide if any. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefautocomplete).
autoFocus	boolean	—	Whether the element should receive focus on render.
disabledKeys	Iterable<Key>	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
form	string	—	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
isDisabled	boolean	—	Whether the input is disabled.
isInvalid	boolean	—	Whether the input value is invalid.
isRequired	boolean	—	Whether user input is required on the input before form submission.
name	string	—	The name of the input, used when submitting an HTML form.
render	DOMRenderFunction<"div", SelectRenderProps>	—	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
validate	((value: Key) => ValidationError \| true)	—	A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead.
validationBehavior	"native" \| "aria"	'native'	Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Related exports

SelectItem, SelectSection

Examples

Status with glyphs and sections

const statuses = [{ id: "open", title: "Open", items: [
  statusOption("todo", "Not started", "todo"),
  statusOption("doing", "In progress", "in-progress"),
] }, { id: "closed", title: "Closed", items: [statusOption("done", "Done", "done")] }];
<Select label="Status" items={statuses} selectedKey={status} onSelectionChange={setStatus} />

Icons and descriptions

<Select label="Visibility" items={[{ id: "me", label: "Only me", leading: { kind: "icon", icon: <User /> }, description: "Private draft" }]} />

Compact, placeholder and error

<Select aria-label="Priority" size="compact" placeholder="Priority" items={priorityOptions()} />

Hand-written sections

<Select label="Assignee">
  <SelectSection title="Design"><SelectItem id="rodrigo" leading={personOption({ id: "rodrigo", name: "Rodrigo" }).leading}>Rodrigo</SelectItem></SelectSection>
</Select>

Literal anatomy

Static component anatomy; bind events in the consuming app.

<Select label="Status" defaultSelectedKey="todo"><SelectSection title="Workflow"><SelectItem id="todo">Todo</SelectItem><SelectItem id="done">Done</SelectItem></SelectSection></Select>