Components
Field
Accessible field structure for labels, controls, descriptions, and validation messages.
Field groups a label, form control, description, and message into one accessible unit. It is built
on Base UI Field, so validation state, disabled state, and ARIA relationships stay in sync.
Field and its parts are exported from @orkest/ui/client. Render them inside a Client Component.
Basic usage#
We only use this for account notices.
import { Box } from '@orkest/ui';
import { Field, FieldDescription, FieldLabel, Input } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Field>
<FieldLabel>Email</FieldLabel>
<Input type="email" placeholder="you@example.com" />
<FieldDescription>We only use this for account notices.</FieldDescription>
</Field>
</Box>
);
}FieldLabel registers a label id that Base UI controls use for aria-labelledby and htmlFor.
FieldDescription and FieldMessage register their ids so the control receives
aria-describedby without manual wiring. Custom controls such as Checkbox and Switch receive the
label id through aria-labelledby; pass htmlFor explicitly when you need native label-click
behavior for a custom control.
Required and optional#
Set required on Field to require the control and show the required indicator. The indicator
keeps the visual asterisk separate from a screen-reader “Required” label, so the state is not
communicated by color alone.
import { Box, Stack } from '@orkest/ui';
import { Field, FieldLabel, Input } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Stack gap={4}>
<Field required>
<FieldLabel>Full name</FieldLabel>
<Input placeholder="Ada Lovelace" />
</Field>
<Field>
<FieldLabel optional>Job title</FieldLabel>
<Input placeholder="Engineer" />
</Field>
</Stack>
</Box>
);
}Horizontal layout#
Use orientation="horizontal" for settings pages where the label sits beside the control.
Shown on your profile.
import { Box } from '@orkest/ui';
import { Field, FieldDescription, FieldLabel, Input } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="26rem">
<Field orientation="horizontal">
<FieldLabel>Display name</FieldLabel>
<Input placeholder="Ada Lovelace" />
<FieldDescription>Shown on your profile.</FieldDescription>
</Field>
</Box>
);
}Validation#
validate and validationMode are delegated to Base UI Field. When the control participates in
the field, FieldMessage shows the validation message automatically and hides it again once the
field becomes valid.
Try typing admin to see validation.
import { Box } from '@orkest/ui';
import { Field, FieldDescription, FieldLabel, FieldMessage, Input } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Field
validate={(value) =>
value === 'admin' ? 'This workspace name is reserved.' : null
}
validationMode="onChange"
>
<FieldLabel>Workspace URL</FieldLabel>
<Input placeholder="acme" />
<FieldDescription>Try typing admin to see validation.</FieldDescription>
<FieldMessage icon />
</Field>
</Box>
);
}The same pattern works with Select and Textarea, which also register with Base UI Field. Type
admin in the example above to see the error appear and then disappear.
Messages#
FieldMessage handles error, success, warning, and info tones. Error messages are announced with
role="alert"; the other tones use role="status".
import { Box, Stack } from '@orkest/ui';
import { Field, FieldLabel, FieldMessage, Input } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Stack gap={4}>
<Field>
<FieldLabel>API key</FieldLabel>
<Input defaultValue="ok_live_9f2c" />
<FieldMessage type="success" icon>
Your key is active.
</FieldMessage>
</Field>
<Field>
<FieldLabel>Storage</FieldLabel>
<Input defaultValue="8.4 GB" />
<FieldMessage type="warning" icon>
You are close to your quota.
</FieldMessage>
</Field>
<Field>
<FieldLabel>Region</FieldLabel>
<Input defaultValue="eu-west-1" />
<FieldMessage type="info" icon>
Data stays in the EU.
</FieldMessage>
</Field>
</Stack>
</Box>
);
}Error messages are only shown while the field is invalid and enabled. Render one message per field;
descriptions and messages are appended to aria-describedby in registration order.
Composing with controls#
Controls that render their own label should use that label instead of FieldLabel. The field still
links descriptions, messages, names, disabled state, and required state.
At most one email per month.
import { Box } from '@orkest/ui';
import { Checkbox, Field, FieldDescription, FieldMessage } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Field>
<Checkbox label="Product updates" defaultChecked />
<FieldDescription>At most one email per month.</FieldDescription>
<FieldMessage type="info">You can unsubscribe at any time.</FieldMessage>
</Field>
</Box>
);
}Used to calculate tax.
import { Box } from '@orkest/ui';
import { Field, FieldDescription, FieldLabel, Select } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Field>
<FieldLabel>Country</FieldLabel>
<Select
options={[
{ value: 'us', label: 'United States' },
{ value: 'ca', label: 'Canada' },
{ value: 'gb', label: 'United Kingdom' },
]}
/>
<FieldDescription>Used to calculate tax.</FieldDescription>
</Field>
</Box>
);
}For radio groups, prefer Fieldset and Legend. A FieldLabel inside Field also names the group
through aria-labelledby.
Disabled#
Managed by your organization.
import { Box } from '@orkest/ui';
import { Field, FieldDescription, FieldLabel, Input } from '@orkest/ui/client';
export function Example() {
return (
<Box width="100%" maxWidth="22rem">
<Field disabled>
<FieldLabel>Account ID</FieldLabel>
<Input defaultValue="acct_9f2c" />
<FieldDescription>Managed by your organization.</FieldDescription>
</Field>
</Box>
);
}Props#
Field#
| Prop | Type | Default |
|---|---|---|
orientation | 'vertical' | 'horizontal' | 'vertical' |
| Places the label above the control or beside it. | ||
controlId | string | — |
| Stable id assigned to the control. Generated when omitted. | ||
required | boolean | false |
| Requires the control and shows the required indicator in FieldLabel. | ||
disabled | boolean | false |
| Disables the field and its controls. | ||
invalid | boolean | false |
| Marks the field invalid. Also accepts validation results from Base UI. | ||
name | string | — |
| Form field name inherited by controls. | ||
validate | (value, formValues) => string | string[] | null | void | Promise<...> | — |
| Custom validation delegated to Base UI Field. | ||
validationMode | 'onSubmit' | 'onBlur' | 'onChange' | 'onSubmit' |
| When Base UI Field runs validation. | ||
validationDebounceTime | number | 0 |
| Debounce in milliseconds for onChange validation. | ||
actionsRef | RefObject<{ validate: () => void }> | — |
| Imperative Base UI Field actions. | ||
dirty / touched | boolean | — |
| External state for validation libraries. | ||
native attributes | HTMLAttributes<HTMLDivElement> | — |
| Class names, styles, data attributes, and refs are forwarded to the root div. | ||
FieldLabel#
| Prop | Type | Default |
|---|---|---|
htmlFor | string | — |
| Explicit control id for native label association. | ||
required | boolean | — |
| Shows the required indicator. Defaults to Field.required. | ||
optional | boolean | false |
| Shows an Optional marker when the field is not required. | ||
disabled | boolean | false |
| Dims the label without disabling the control. | ||
native attributes | LabelHTMLAttributes<HTMLLabelElement> | — |
| Class names, styles, and refs are forwarded to the label element. | ||
FieldDescription#
| Prop | Type | Default |
|---|---|---|
id | string | — |
| Description id. Generated and registered with the field when omitted. | ||
native attributes | HTMLAttributes<HTMLParagraphElement> | — |
| Class names and refs are forwarded to the paragraph. | ||
FieldMessage#
| Prop | Type | Default |
|---|---|---|
type | 'error' | 'success' | 'warning' | 'info' | 'error' |
| Tone and status role of the message. | ||
icon | boolean | false |
| Shows the icon that matches the message type. | ||
children | ReactNode | — |
| Message content. Error messages fall back to Base UI validation errors. | ||
id | string | — |
| Message id. Generated and registered with the field when omitted. | ||
native attributes | HTMLAttributes<HTMLDivElement> | — |
| Class names, roles, and refs are forwarded. | ||
FieldRequiredIndicator#
| Prop | Type | Default |
|---|---|---|
children | ReactNode | '*' |
| Visual marker, hidden from assistive technology. | ||
srLabel | string | 'Required' |
| Screen-reader text that carries the required meaning. | ||
Accessibility#
FieldLabelregisters a label id. Base UI controls use it forhtmlForandaria-labelledby; custom controls such as Checkbox and Switch receivearia-labelledby. PasshtmlForexplicitly when a custom control needs native label-click behavior.- Descriptions and messages are added to
aria-describedby. Multiple ids are supported. - Invalid fields set
aria-invalidon the control. Error messages userole="alert"; success, warning, and info messages userole="status". - Required fields set the native
requiredattribute and include screen-reader text in the label. Fieldsetuses a native<fieldset>with a native<legend>, so the group has an accessible name and shared disabled state.- Disabled state uses native attributes and muted text, not color alone.
- The horizontal layout uses a grid; DOM order remains label, control, description, message, so keyboard and screen-reader order do not change.