Field
Accessible composition for labels, controls, descriptions, native validity, and errors.
Contract
TRField wraps the complete Base UI Field anatomy. Label, Description, and visible Error parts are automatically associated with the field control. A root name or disabled prop takes precedence over the same prop on Control.
| Part | Responsibility |
|---|---|
Root | name, availability, validation timing, and dirty/touched/filled/focused state |
Label | accessible name and click-to-focus target |
Control | native input value, events, validity, form data, and reset behavior |
Description | persistent instructions included in aria-describedby |
Error | native-validity or externally controlled recovery message |
Validity | render-prop access to value, errors, and native ValidityState |
Item | label-and-description layout for one checkbox or radio in a collection |
Use disabled when the field must be unavailable and omitted from form data. Use readOnly on Control when its value must remain focusable and submitted. Do not manually add aria-labelledby or aria-describedby when using the standard parts.
Install
pnpm add @tinyrack/uiScroll inside the code area to read long lines.
Styles
@import '@tinyrack/ui/components/field.css';Scroll inside the code area to read long lines.
Imports
import { TRField } from '@tinyrack/ui/components/field';Scroll inside the code area to read long lines.
Playground
Type in the preview to change its interaction-owned value. Playground controls expose required, invalid, read-only, disabled, and size; Reset restores them and the preview value.
Usage
Examples
Sizes permalink
Match field density to nearby controls and content.
Availability and validity states permalink
Use invalid for recovery feedback, disabled to omit a value from form data, and readOnly to preserve a focusable submitted value.
Submit, recover, and reset permalink
Native email validity selects the matching error. Reset restores both the input and application feedback.
Collection item and validity data permalink
Item aligns each option with its label and description. Validity reads the field state without duplicating validation rules.
API
TRField.Root
| Prop | Type / default | Purpose |
|---|---|---|
name | string | names the field and overrides Control.name |
disabled | boolean / false | disables the associated control and marks every part data-disabled |
invalid, dirty, touched | boolean | supplies externally controlled field state |
validate | sync or async validator | returns one error, multiple errors, or null |
validationMode | 'onSubmit' | 'onBlur' | 'onChange' / 'onSubmit' | chooses when validation runs |
validationDebounceTime | number / 0 | debounces onChange validation in milliseconds |
actionsRef | RefObject<TRFieldRootActions> | exposes validate() |
Parts
Control accepts native input props plus controlled value, uncontrolled defaultValue, and onValueChange(value, details). Size lives on the control, not on Root: Control accepts uiSize?: 'md' | 'lg' (default md), and every other Tinyrack control carries the same prop, so one rule applies whether the control sits inside a Root or stands alone. Label.nativeLabel={false} is available when render replaces the native label with a non-label host. Error.match accepts true or a ValidityState key such as valueMissing, typeMismatch, or patternMismatch. Item.disabled disables one collection item. Validity requires a render function and exposes validity, value, initialValue, error, and errors.
Every host part preserves refs, native attributes and events, functional className/style, and Base UI render. Root and host parts expose data-disabled, data-valid, data-invalid, data-dirty, data-touched, data-filled, and data-focused.
The namespace, all seven named parts, every part prop/state type, TRFieldRootActions, TRFieldValidityData, TRFieldControlChangeEventReason, and TRFieldControlChangeEventDetails are individually exported from @tinyrack/ui/components/field. CSS remains opt-in.