Primitives

Field primitive

Shared label, description, and validation parts for custom fields.

Use the field primitives to build a custom field with Luke UI labels, descriptions, and validation messages. Start with TextInputField, ComboboxField, SelectField, CheckboxField, or SwitchField when one of those components fits.

Field primitive: Basic

Open in playground

EmailUse your work email.

import { Field } from '@luke-ui/react/primitives/field';
import { TextInput, TextInputRoot } from '@luke-ui/react/primitives/text-input';

export default () => {
	return (
		<TextInputRoot name="email" type="email">
			<Field description="Use your work email." label="Email">
				<TextInput />
			</Field>
		</TextInputRoot>
	);
};

Field primitive: Basic

Loading Field primitive: Basic example

Anatomy

Field provides the standard stacked anatomy: a label, the control, a description, and an error slot. It always renders the error slot, so a validation message appears without extra markup.

Field provides presentation, not semantics. Render it inside a control root, such as TextInputRoot or ComboboxRoot. The root connects the label, description, and error to the control, so the parts need no manual ids.

InlineField is the counterpart for a control that carries its own label, such as CheckboxRoot or SwitchRoot. It wraps the control's label part, such as CheckboxLabel or SwitchLabel, takes a description and an errorMessage, and indents the error under the label text. Like Field, it needs a surrounding control root.

FieldLabel, FieldDescription, and FieldError are the lower-level alternative for a custom arrangement. Place them directly inside the control root, as the TextInput primitives page shows. Use either Field, InlineField, or the manual parts for one field, never a mix. Inside CheckboxRoot or SwitchRoot, a FieldLabel replaces the text in CheckboxLabel or SwitchLabel and toggles the control when clicked.

Required fields

necessityIndicator controls the visible marker on FieldLabel and InlineLabelText. When omitted, it inherits from the surrounding Form. Without either setting, required labels use 'required-asterisk'.

The indicator does not make a control required. Set isRequired on the control root, or required on an associated native input.

isRequired on FieldLabel or InlineLabelText describes the control's state for the marker. It does not set the control's required semantics. Place it on the label part next to a native control with required. Inside a Luke UI control root, the root's required state wins.

<label>
	<input required type="checkbox" />
	<InlineLabelText isRequired>Accept the terms</InlineLabelText>
</label>

A composed Field named only through aria-label or aria-labelledby has no label to render, so it shows no marker. Read Required fields for the three indicator values and when to add a legend.

Validation messages

Use errorMessage for validation feedback. FieldError renders a block container with a leading error icon while the surrounding control root is invalid. It supports inline text and structured content such as a list of validation requirements.

API

FieldProps

FieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
description	ReactNode
Optional helper text shown below the control.
errorMessage	ChildrenOrFunction<FieldErrorRenderProps>
Error content passed to `FieldError`. Accepts React Aria's render-prop form.
label	ReactNode
Label content shown above the control.
necessityIndicator
Controls how the label identifies required or optional values. Inherits from `Form`, or uses `'required-asterisk'` when unset.

InlineFieldProps

InlineFieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
description	ReactNode
Optional helper text shown below the control, at the field's inline start.
errorMessage	ChildrenOrFunction<FieldErrorRenderProps>
Error content passed to `FieldError`. Accepts React Aria's render-prop form.

FieldLabelProps

FieldLabelProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
htmlFor	string \|⁠ undefined
Associates the label with a form control.
necessityIndicator
Controls how the label identifies required or optional values. Inherits from `Form`, or uses `'required-asterisk'` when unset.

InlineLabelTextProps

InlineLabelTextProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
necessityIndicator
Controls how the label identifies required or optional values. Inherits from `Form`, or uses `'required-asterisk'` when unset.

FieldDescriptionProps

FieldDescriptionProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type

FieldErrorProps

FieldErrorProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type