--- title: Field subtitle: A component that provides labeling and validation for form controls. description: A high-quality, unstyled React field component that provides labeling and validation for form controls. --- > FineSoft Components documentation. Independent Stencil port; not the official Base UI website. > > React API text and `@base-ui/react` examples are upstream references. FineSoft Stencil examples use `finesoft-components`. Do not treat the two packages as interchangeable. # Field A high-quality, unstyled React field component that provides labeling and validation for form controls. ## Demo ### Tailwind This example shows how to implement the component using Tailwind CSS. ```tsx /* docs-comparison.tsx */ import { StencilComparison } from 'docs/src/components/StencilComparison'; import ReactField from './react-field'; import StencilField from './stencil-field'; export default function FieldComparison() { return } stencil={} />; } ``` ```tsx /* react-field.tsx */ import { Field } from '@base-ui/react/field'; export default function ExampleField() { return ( Name Please enter your name Visible on your profile ); } ``` ```tsx /* stencil-field.tsx */ export default function StencilField() { return ( Name Please enter your name Visible on your profile ); } ``` ### CSS Modules This example shows how to implement the component using CSS Modules. ```css /* index.module.css */ .Field { display: flex; flex-direction: column; align-items: start; gap: 0.25rem; width: 100%; max-width: 16rem; } .Label { font-size: 0.875rem; line-height: 1.25rem; font-weight: 700; color: oklch(14.5% 0 0deg); @media (prefers-color-scheme: dark) { color: white; } } .Input { box-sizing: border-box; padding: 0 0.5rem; margin: 0; border-radius: 0; border: 1px solid oklch(14.5% 0 0deg); width: 100%; height: 2rem; font-family: inherit; font-size: 0.875rem; line-height: 1.25rem; font-weight: 400; background-color: white; color: oklch(14.5% 0 0deg); @media (any-pointer: coarse) { font-size: 1rem; line-height: 1.5rem; } @media (prefers-color-scheme: dark) { border: 1px solid white; background-color: oklch(14.5% 0 0deg); color: white; } &::placeholder { color: oklch(55.6% 0 0deg); @media (prefers-color-scheme: dark) { color: oklch(70.8% 0 0deg); } } &:focus { outline: 2px solid oklch(14.5% 0 0deg); outline-offset: -1px; @media (prefers-color-scheme: dark) { outline-color: white; } } } .Error { font-size: 0.875rem; line-height: 1.25rem; color: oklch(50.5% 0.213 27.518deg); @media (prefers-color-scheme: dark) { color: oklch(70.4% 0.191 22.216deg); } } .Description { margin: 0; font-size: 0.875rem; line-height: 1.25rem; color: oklch(43.9% 0 0deg); @media (prefers-color-scheme: dark) { color: oklch(70.8% 0 0deg); } } ``` ```tsx /* docs-comparison.tsx */ import { StencilComparison } from 'docs/src/components/StencilComparison'; import ReactField from './react-field'; import StencilField from './stencil-field'; export default function FieldComparison() { return } stencil={} />; } ``` ```tsx /* react-field.tsx */ import { Field } from '@base-ui/react/field'; import styles from './index.module.css'; export default function ExampleField() { return ( Name Please enter your name Visible on your profile ); } ``` ```tsx /* stencil-field.tsx */ export default function StencilField() { return ( Name Please enter your name Visible on your profile ); } ``` The Stencil example uses `fs-field-root`, `fs-field-label`, `fs-field-control`, `fs-field-error`, and `fs-field-description` with the same required-input validation. The migrated [Form](/react/components/form.md) supplies inherited validation mode, consolidated values, form-level errors, submit validation, and first-invalid-control focus. The native input is shared by `fs-field-control` and `fs-input`. Existing Stencil Checkbox, Checkbox Group, Radio, Switch, Slider, Number Field and OTP Field also inherit Field state, labels, descriptions and validation. Use `inputRef` for the actual native Field Control input. `actionsRef.current.validate()` (or the Root element's `validateField()` method) triggers validation. `fs-field-validity` exposes its snapshot through `validity` / `getValidity()` and the `validityChange` event instead of React's function child; in React, listen with `onvalidityChange` and read `event.detail`. Error mounts only while its condition matches, retaining the last message until its exit animation finishes. Root, Item, and Description use Shadow DOM and expose `::part(field)`, `::part(item)`, and `::part(description)`. The Base UI theme is built in; set `data-fs-theme="base-ui"` on an ancestor to apply the default appearance without component classes. CSS variables and these parts support custom styling. Control and Label retain native input and label elements in Light DOM for form ownership and label activation. Error keeps its existing content and animation boundary; Validity remains a transparent state API. ## Anatomy Import the component and assemble its parts: ```jsx title="Anatomy" import { Field } from '@base-ui/react/field'; ; ``` ## API reference ### Root Groups all parts of the field. Renders a `
` element. **Root Props:** | Prop | Type | Default | Description | | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | :----------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | name | `string` | - | Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `` component. | | actionsRef | `React.RefObject` | - | A ref to imperative actions. `validate`: Validates the field when called. | | dirty | `boolean` | - | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. | | touched | `boolean` | - | Whether the field has been touched. Useful when the field state is controlled by an external library. | | disabled | `boolean` | `false` | Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `` component. | | invalid | `boolean` | - | Whether the field is invalid. Useful when the field state is controlled by an external library. | | validate | `((value: unknown, formValues: Form.Values) => string \| void \| string[] \| Promise \| null)` | - | A function for custom validation. Return a string or an array of strings with the error message(s) if the value is invalid. Returning nothing, `null`, an empty string, or an empty array means the value is valid. Asynchronous functions are supported, but they do not prevent form submission when using `validationMode="onSubmit"`. | | validationMode | `Form.ValidationMode` | `'onSubmit'` | Determines when the field should be validated. This takes precedence over the `validationMode` prop on `
`. `onSubmit`: triggers validation when the form is submitted, and re-validates on change after submission.`onBlur`: triggers validation when the control loses focus.`onChange`: triggers validation on every change to the control value. | | validationDebounceTime | `number` | `0` | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds. | | className | `string \| ((state: Field.Root.State) => string \| undefined)` | - | CSS class applied to the element, or a function that returns a class based on the component's state. | | style | `React.CSSProperties \| ((state: Field.Root.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that returns a style object based on the component's state. | | render | `ReactElement \| ((props: HTMLProps, state: Field.Root.State) => ReactElement)` | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. | **Root Data Attributes:** | Attribute | Type | Description | | :------------ | :--- | :------------------------------------------ | | data-disabled | - | Present when the field is disabled. | | data-valid | - | Present when the field is valid. | | data-invalid | - | Present when the field is invalid. | | data-dirty | - | Present when the field's value has changed. | | data-touched | - | Present when the field has been touched. | | data-filled | - | Present when the field is filled. | | data-focused | - | Present when the field control is focused. | ### Root.Props Re-export of [Root](/react/components/field.md) props. ### Root.State ```typescript type FieldRootState = { /** Whether the component should ignore user interaction. */ disabled: boolean; /** Whether the field has been touched. */ touched: boolean; /** Whether the field value has changed from its initial value. */ dirty: boolean; /** Whether the field is valid. */ valid: boolean | null; /** Whether the field has a value. */ filled: boolean; /** Whether the field is focused. */ focused: boolean; }; ``` ### Root.Actions ```typescript type FieldRootActions = { validate: () => void }; ``` ### Item Groups individual items in a checkbox group or radio group with a label and description. Renders a `
` element. **Item Props:** | Prop | Type | Default | Description | | :-------- | :--------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | disabled | `boolean` | `false` | Whether the wrapped control should ignore user interaction. The `disabled` prop on `` takes precedence over this. | | className | `string \| ((state: Field.Item.State) => string \| undefined)` | - | CSS class applied to the element, or a function that returns a class based on the component's state. | | style | `React.CSSProperties \| ((state: Field.Item.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that returns a style object based on the component's state. | | render | `ReactElement \| ((props: HTMLProps, state: Field.Item.State) => ReactElement)` | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. | **Item Data Attributes:** | Attribute | Type | Description | | :------------ | :--- | :--------------------------------------------- | | data-disabled | - | Present when the field is disabled. | | data-valid | - | Present when the field is in a valid state. | | data-invalid | - | Present when the field is in an invalid state. | | data-dirty | - | Present when the field's value has changed. | | data-touched | - | Present when the field has been touched. | | data-filled | - | Present when the field is filled. | | data-focused | - | Present when the field control is focused. | ### Item.Props Re-export of [Item](/react/components/field.md) props. ### Item.State ```typescript type FieldItemState = { /** Whether the component should ignore user interaction. */ disabled: boolean; /** Whether the field has been touched. */ touched: boolean; /** Whether the field value has changed from its initial value. */ dirty: boolean; /** Whether the field is valid. */ valid: boolean | null; /** Whether the field has a value. */ filled: boolean; /** Whether the field is focused. */ focused: boolean; }; ``` ### Description A paragraph with additional information about the field. Renders a `

` element. **Description Props:** | Prop | Type | Default | Description | | :-------- | :---------------------------------------------------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | className | `string \| ((state: Field.Description.State) => string \| undefined)` | - | CSS class applied to the element, or a function that returns a class based on the component's state. | | style | `React.CSSProperties \| ((state: Field.Description.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that returns a style object based on the component's state. | | render | `ReactElement \| ((props: HTMLProps, state: Field.Description.State) => ReactElement)` | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. | **Description Data Attributes:** | Attribute | Type | Description | | :------------ | :--- | :--------------------------------------------- | | data-disabled | - | Present when the field is disabled. | | data-valid | - | Present when the field is in a valid state. | | data-invalid | - | Present when the field is in an invalid state. | | data-dirty | - | Present when the field's value has changed. | | data-touched | - | Present when the field has been touched. | | data-filled | - | Present when the field is filled. | | data-focused | - | Present when the field control is focused. | ### Description.Props Re-export of [Description](/react/components/field.md) props. ### Description.State ```typescript type FieldDescriptionState = { /** Whether the component should ignore user interaction. */ disabled: boolean; /** Whether the field has been touched. */ touched: boolean; /** Whether the field value has changed from its initial value. */ dirty: boolean; /** Whether the field is valid. */ valid: boolean | null; /** Whether the field has a value. */ filled: boolean; /** Whether the field is focused. */ focused: boolean; }; ``` ### Control The form control to label and validate. Renders an `` element. You can omit this part and use any Base UI input component instead. For example, [Input](https://base-ui.com/react/components/input), [Checkbox](https://base-ui.com/react/components/checkbox), or [Select](https://base-ui.com/react/components/select), among others, will work with Field out of the box. **Control Props:** | Prop | Type | Default | Description | | :------------ | :------------------------------------------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | defaultValue | `string \| number \| string[]` | - | - | | onValueChange | `((value: string, eventDetails: Field.Control.ChangeEventDetails) => void)` | - | Callback fired when the `value` changes. Use when controlled. | | className | `string \| ((state: Field.Control.State) => string \| undefined)` | - | CSS class applied to the element, or a function that returns a class based on the component's state. | | style | `React.CSSProperties \| ((state: Field.Control.State) => React.CSSProperties \| undefined)` | - | Style applied to the element, or a function that returns a style object based on the component's state. | | render | `ReactElement \| ((props: HTMLProps, state: Field.Control.State) => ReactElement)` | - | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. | **Control Data Attributes:** | Attribute | Type | Description | | :------------ | :--- | :--------------------------------------------- | | data-disabled | - | Present when the field is disabled. | | data-valid | - | Present when the field is in a valid state. | | data-invalid | - | Present when the field is in an invalid state. | | data-dirty | - | Present when the field's value has changed. | | data-touched | - | Present when the field has been touched. | | data-filled | - | Present when the field is filled. | | data-focused | - | Present when the field control is focused. | ### Control.Props Re-export of [Control](/react/components/field.md) props. ### Control.State ```typescript type FieldControlState = { /** Whether the component should ignore user interaction. */ disabled: boolean; /** Whether the field has been touched. */ touched: boolean; /** Whether the field value has changed from its initial value. */ dirty: boolean; /** Whether the field is valid. */ valid: boolean | null; /** Whether the field has a value. */ filled: boolean; /** Whether the field is focused. */ focused: boolean; }; ``` ### Control.ChangeEventReason ```typescript type FieldControlChangeEventReason = 'none'; ``` ### Control.ChangeEventDetails ```typescript type FieldControlChangeEventDetails = { /** The reason for the event. */ reason: 'none'; /** The native event associated with the custom event. */ event: Event; /** Cancels Base UI from handling the event. */ cancel: () => void; /** Allows the event to propagate in cases where Base UI will stop the propagation. */ allowPropagation: () => void; /** Indicates whether the event has been canceled. */ isCanceled: boolean; /** Indicates whether the event is allowed to propagate. */ isPropagationAllowed: boolean; /** The element that triggered the event, if applicable. */ trigger: Element | undefined; }; ``` ### Label An accessible label that is automatically associated with the field control. Renders a `

`). This is useful to avoid inheriting label behaviors on `