# Select Field (/components/forms/select-field)
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`](/components/forms/combobox-field) instead when searching or filtering the options
helps.
apps/docs/src/examples/select-field/basic.tsx
```tsx
import { SelectField, SelectItem } from '@luke-ui/react/select-field';
import { Stack } from '@luke-ui/react/stack';
const themes = [
{ id: 'system', label: 'System' },
{ id: 'light', label: 'Light' },
{ id: 'dark', label: 'Dark' },
];
export default () => {
return (
{(item) => {item.label}}
);
};
```
## Items and selection [#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.
apps/docs/src/examples/select-field/controlled.tsx
```tsx
import { SelectField, SelectItem } from '@luke-ui/react/select-field';
import { Stack } from '@luke-ui/react/stack';
import { Text } from '@luke-ui/react/text';
import { useState } from 'react';
const sizes = [
{ id: 'small', label: 'Small' },
{ id: 'default', label: 'Default' },
{ id: 'large', label: 'Large' },
];
export default () => {
const [size, setSize] = useState('default');
return (
{(item) => {item.label}}
{`Selected key: ${size ?? 'none'}`}
);
};
```
## Required fields [#required-fields]
Set `isRequired` to make a selection mandatory. Use `necessityIndicator` to choose how it appears
beside the label.
apps/docs/src/examples/select-field/required.tsx
```tsx
import { SelectField, SelectItem } from '@luke-ui/react/select-field';
const countries = [
{ id: 'australia', label: 'Australia' },
{ id: 'canada', label: 'Canada' },
{ id: 'new-zealand', label: 'New Zealand' },
];
export default () => {
return (
{(item) => {item.label}}
);
};
```
## Validation [#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](/docs/validation) for where messages come from, server errors, and how to write them.
apps/docs/src/examples/select-field/validation.tsx
```tsx
import { Button } from '@luke-ui/react/button';
import { Cluster } from '@luke-ui/react/cluster';
import { SelectField, SelectItem } from '@luke-ui/react/select-field';
import { Stack } from '@luke-ui/react/stack';
import type { SubmitEvent } from 'react';
const countries = [
{ id: 'australia', label: 'Australia' },
{ id: 'canada', label: 'Canada' },
{ id: 'new-zealand', label: 'New Zealand' },
];
export default () => {
function handleSubmit(event: SubmitEvent) {
event.preventDefault();
}
return (
);
};
```
To move focus to the trigger yourself, pass `triggerRef`. `ref` reaches the root element.
## Disabled, pending, and fixed values [#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 [#size]
Use `size` to set the control height and typography. Use `small` in compact layouts. `medium` is the
default.
apps/docs/src/examples/select-field/sizes.tsx
```tsx
import { SelectField, SelectItem } from '@luke-ui/react/select-field';
import { Comparison, ComparisonItem } from '#docs';
const options = [
{ id: 'one', label: 'Example option' },
{ id: 'two', label: 'Another option' },
];
export default () => {
return (
{(item) => {item.label}}
{(item) => {item.label}}
);
};
```
## Accessibility [#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 [#api]
### SelectFieldProps [#selectfieldprops]
### SelectFieldProps
Props for `SelectField`.
`SelectFieldProps` also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.
| Prop | Type | Description |
| --------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aria-describedby?` | `string` | Identifies the element (or elements) that describes the object. |
| `aria-details?` | `string` | Identifies the element (or elements) that provide a detailed, extended description for the object. |
| `onKeyDown?` | `function` | Handler that is called when a key is pressed. |
| `onKeyUp?` | `function` | Handler that is called when a key is released. |
| `onFocus?` | `function` | Handler that is called when the element receives focus. |
| `onBlur?` | `function` | Handler that is called when the element loses focus. |
| `onFocusChange?` | `function` | Handler that is called when the element's focus status changes. |
| `description?` | `ReactNode` | Optional helper text shown below the control. |
| `necessityIndicator?` | `union` | Label necessity style. Default: `'icon'` |
| `label?` | `union` | Visible label. Pass non-empty, textual, non-interactive content. Place links and buttons outside it, and associate external label content with `aria-labelledby` instead. |
| `aria-label?` | `string` | |
| `aria-labelledby?` | `string` | |
| `autoComplete?` | `string` | Describes the type of autocomplete the browser may offer for the hidden form control. |
| `autoFocus?` | `union` | Whether the select should receive focus on render. |
| `form?` | `string` | The `