Select Field
Single-selection field with a label, validation, and a popover list of options.
Use SelectField when someone chooses one option from a predefined list. It combines a trigger
button, label, description, validation message, popover, and listbox. Use
ComboboxField instead when searching or filtering the options
helps.
Items and selection
Pass items and a render function that returns a SelectItem for each one. Import SelectItem
from @luke-ui/react/select-field.
Each option needs a stable id. Give each item in items an id or key, or give each SelectItem
an id when your data has neither. When the items carry an id or key, value, onChange, and
validate use the inferred key type, so string ids give string | null for value and string
for validate. Otherwise selection values use Key | null, and validate receives Key. React
Aria doesn't call validate while nothing is selected.
For a fixed set of options, pass SelectItem children with an id each instead of items.
SelectField holds one selected option and has no clear button. An option labelled “None” is a
choice like any other: selecting it selects its key and doesn't empty the field.
Pass defaultValue to start with an option selected. Pass value and onChange to control the
selection yourself. onChange receives the selected key, or null when nothing is selected, and
value takes the same type.
Required fields
Set isRequired to make a selection mandatory. Use necessityIndicator to choose how it appears
beside the label.
Validation
Set isRequired or pass validate to check the selected key. SelectField shows its validation
message after validation fails. Pass errorMessage only for an error you already have, such as one
from a form library or your server. A non-empty message marks the field invalid. Read
Validation for where messages come from, server errors, and how to write them.
To move focus to the trigger yourself, pass triggerRef. ref reaches the root element.
Disabled, pending, and fixed values
SelectField has no read-only state. Show a value that can't change as text instead.
Set isDisabled to block the field. A disabled field can't take focus and doesn't submit its value.
Pass isPending while a change is saving. The trigger keeps focus but can't be pressed or opened,
and can't change the value from the trigger, until pending ends.
Size
Use size to set the control height and typography. Use small in compact layouts. medium is the
default.
Accessibility
The select needs an accessible name. Use the visible label. Without one, pass aria-labelledby to
point at content already on the page, or aria-label to supply the name directly. A placeholder
doesn't name the field.
API
SelectFieldProps
SelectFieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
Prop
Type
SelectItemProps
SelectItemProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
Prop
Type