# @fayegram-ai/faye-ui/controls/field

Public exports and dependency-resolved component properties, with usage and rendering guidance.

## Import

```tsx
import { Field } from '@fayegram-ai/faye-ui/controls/field';
```

[Usage and behavior guide](/docs/fields/) · [API JSON](/api/packages/controls/field.json)

This entry declares a client boundary. Follow the rendering guide for framework integration.

## Public exports

| Name | Kind | Resolved declaration type |
|---|---|---|
| `Field` | value | `{ readonly Control: import("react").ForwardRefExoticComponent<Omit<import("@base-ui/react").FieldControlProps, "ref"> & import("react").RefAttributes<HTMLElement>>; readonly Validity: import("react").FC<import("@base-ui/react").FieldValidityProps>; readonly Root: { (input: Omit<import("@base-ui/react").FieldRootProps, "ref"> & import("react").RefAttributes<HTMLDivElement> & { variants?: { readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> \| undefined; } \| undefined; }): import("react").ReactElement; displayName: string; }; readonly Label: { (input: Omit<import("@base-ui/react").FieldLabelProps, "ref"> & import("react").Ref… (full type in API JSON)` |

## Field

Public component; use the linked family guide for complete composition and behavior.

Dependency-resolved declaration properties. Common React/native HTML attributes are omitted from the table; use the full declaration and React/native references. Generic and union restrictions remain authoritative in TypeScript.

### Field.Control

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: FieldControlState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `defaultValue` | No | `string \| number \| readonly string[] \| undefined` | See the usage contract and declaration. |
| `onValueChange` | No | `((value: string, eventDetails: FieldControl.ChangeEventDetails) => void) \| undefined` | Callback fired when the `value` changes. Use when controlled. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldControlState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: FieldControlState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |

### Field.Validity

| Property | Required | Type | Meaning |
|---|---|---|---|
| `children` | Yes | `(state: FieldValidityState) => React.ReactNode` | A function that accepts the field validity state as an argument. ```jsx <Field.Validity> {(validity) => { return <div>...</div> }} </Field.Validity> ``` |

### Field.Root

| Property | Required | Type | Meaning |
|---|---|---|---|
| `actionsRef` | No | `RefObject<FieldRootActions \| null> \| undefined` | A ref to imperative actions. - `validate`: Validates the field when called. |
| `className` | No | `string \| ((state: FieldRootState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `dirty` | No | `boolean \| undefined` | Whether the field's value has been changed from its initial value. Useful when the field state is controlled by an external library. |
| `disabled` | No | `boolean \| undefined` | Whether the component should ignore user interaction. Takes precedence over the `disabled` prop on the `<Field.Control>` component. |
| `invalid` | No | `boolean \| undefined` | Whether the field is invalid. Useful when the field state is controlled by an external library. |
| `name` | No | `string \| undefined` | Identifies the field when a form is submitted. Takes precedence over the `name` prop on the `<Field.Control>` component. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldRootState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: FieldRootState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `touched` | No | `boolean \| undefined` | Whether the field has been touched. Useful when the field state is controlled by an external library. |
| `validate` | No | `((value: unknown, formValues: Form.Values) => string \| string[] \| null \| void \| Promise<string \| string[] \| null \| void>) \| undefined` | 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"`. |
| `validationDebounceTime` | No | `number \| undefined` | How long to wait between `validate` callbacks if `validationMode="onChange"` is used. Specified in milliseconds. |
| `validationMode` | No | `FormValidationMode \| undefined` | Determines when the field should be validated. This takes precedence over the `validationMode` prop on `<Form>`. - `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. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Field.Label

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: FieldLabelState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `nativeLabel` | No | `boolean \| undefined` | Whether the component renders a native `<label>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a label (for example, `<div>`). This is useful to avoid inheriting label behaviors on `<button>` controls (such as `<Select.Trigger>` and `<Combobox.Trigger>`), including avoiding `:hover` on the button when hovering the label, and preventing clicks on the label from firing on the button. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldLabelState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: FieldLabelState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Field.Description

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: FieldDescriptionState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldDescriptionState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: FieldDescriptionState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

### Field.Error

| Property | Required | Type | Meaning |
|---|---|---|---|
| `className` | No | `string \| ((state: FieldErrorState) => string \| undefined) \| undefined` | CSS class applied to the element, or a function that returns a class based on the component's state. |
| `match` | No | `boolean \| keyof ValidityState \| undefined` | Determines whether to show the error message according to the field's [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState). Specifying `true` will always show the error message, and lets external libraries control the visibility. |
| `render` | No | `ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, FieldErrorState> \| undefined` | 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. |
| `style` | No | `CSSProperties \| ((state: FieldErrorState) => React.CSSProperties \| undefined) \| undefined` | Style applied to the element, or a function that returns a style object based on the component's state. |
| `variants` | No | `{ readonly size?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "size"> \| undefined; readonly tone?: import("@fayegram-ai/faye-ui/contracts/visual-variants").VisualVariant<"field", "tone"> \| undefined; } \| undefined` | See the usage contract and declaration. |

## Defaults and customization

Descriptor defaults: `{"size":"md","tone":"neutral"}`. Parts: `root`, `label`, `description`, `error`. Explicit instance props take precedence over configured defaults.

Use semantic tokens, public part hooks and customization sheets. Keep visual configuration separate from application state.

## State, events and accessibility

For interactive controls, pair a controlled value/open prop with its corresponding change callback; default props initialize uncontrolled state. Keep application validation and submission policy explicit. Name controls with visible labels, name icon-only actions on the button, and preserve focus and dismissal behavior when replacing parts. Use native form names and submit/reset types where supported. See the usage guide for component-specific behavior and live examples.

## Declaration authority

Generated from `packages/faye-ui/dist/controls/field.d.ts` after the semantic package build. Common native/React attributes are intentionally omitted from property tables. Generic overloads, discriminated unions and complete inherited attributes remain authoritative in installed TypeScript declarations. [React DOM attributes](https://react.dev/reference/react-dom/components/common) and [Base UI component contracts](https://base-ui.com/react/overview/quick-start) describe the inherited foundations.