Chapter 23: Field

Core Idea

The wrapper that ties a form control's label, description, and error message together with automatic ARIA association and a shared set of validation-state data attributes (data-valid/data-invalid/data-dirty/data-touched/data-filled/data-focused) — the accessibility and validation backbone documented in depth in ch009 (Forms).

Key Concepts

• Anatomy: Root → Label, Control, Description, Item, Error, Validity.
• Root.name: registers this field's value under that key when submitted via a parent Form (see ch009, ch025).
• Root.validate/validationMode/validationDebounceTime: the custom-validation trio detailed in ch009.
• Control: generic wrapper for a form control when it isn't already a Base UI component with its own field-state attributes — accepts defaultValue/onValueChange directly.
• Error.match: selects which native validity-state key (valueMissing, patternMismatch, tooShort, ...) this particular Error instance displays for — lets you show different messages for different failure reasons on the same field.
• Validity: render-prop-only part (children as a function) for reading the field's live validity state directly, when neither Error nor the shared data attributes are flexible enough.
• Shared state attributes (data-valid, data-invalid, data-dirty, data-touched, data-filled, data-focused, data-disabled) appear on nearly every Field part and on most form controls throughout the library (Input, Checkbox, Autocomplete, Combobox, ...) — this is the single vocabulary to learn once and reuse everywhere.

Reference Tables

Part	Notable props	Notable data attributes
Root	name, validate, validationMode, validationDebounceTime, disabled, invalid, dirty, touched, actionsRef	data-valid/data-invalid, data-dirty, data-touched, data-filled, data-focused, data-disabled
Label	nativeLabel	same shared state attributes
Control	defaultValue, onValueChange	same shared state attributes
Error	match	same shared state attributes + data-starting-style/data-ending-style
Item	disabled	same shared state attributes

Key Takeaways

1. Learn the six shared field-state data attributes here once — they recur on nearly every form-capable component in the library rather than being Field-specific.
2. Use Error.match to give distinct messages per validity reason (required vs. pattern vs. length) on one field, instead of one generic error string.
3. Reach for Field.Control specifically when wrapping a plain native <input>/<textarea> or a third-party control that isn't already a Base UI part with its own field-state wiring.

Connects To

• ch009 (Forms): the full workflow (naming, validation modes, server errors) this chapter's parts implement.
• ch024 (Fieldset): groups multiple Field.Roots under one legend/label.
• ch025 (Form): the submission container Field.Root is meant to live inside.