> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Field

> Connect a form control to its label, description, and validation feedback.

Use `Field` to group one control with its accessible label and helper text. Components such as [Input](/ui/components/input/input) integrate with the field directly.

## Labeled control

```tsx theme={null}
import { Field, Input } from 'twenty-ui/input';

export const EmailField = () => (
  <Field.Root name="email" validationMode="onBlur">
    <Field.Label>Work email</Field.Label>
    <Input type="email" required placeholder="you@example.com" />
    <Field.Description>
      We send account updates to this address.
    </Field.Description>
    <Field.Error match="valueMissing">Enter your email address.</Field.Error>
    <Field.Error match="typeMismatch">Enter a valid email address.</Field.Error>
  </Field.Root>
);
```

`Field.Root` manages the control's name, disabled state, and validity. `Field.Label` and `Field.Description` connect their content to the control. Set validation timing with `validationMode`; use `validate` for custom validation.

## External errors

Use `invalid` when your application owns the error state. An explicit `match` makes the error message visible.

```tsx theme={null}
import { Field, Input } from 'twenty-ui/input';

type UsernameFieldProps = { error?: string };

export const UsernameField = ({ error }: UsernameFieldProps) => (
  <Field.Root name="username" invalid={Boolean(error)}>
    <Field.Label>Username</Field.Label>
    <Input autoComplete="username" />
    <Field.Error match={Boolean(error)}>{error}</Field.Error>
  </Field.Root>
);
```

## Parts

| Part          | Purpose                                              |
| ------------- | ---------------------------------------------------- |
| `Root`        | Shares field state and validation with the control.  |
| `Label`       | Names the control.                                   |
| `Control`     | Provides an unstyled input with field integration.   |
| `Description` | Adds persistent helper text.                         |
| `Error`       | Shows feedback for a matching validation state.      |
| `Validity`    | Exposes validity through a children render function. |

Keep error messages actionable and provide a visible label even when the control has a placeholder.

## Props

The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.

### Field.Root

<ParamField body="Root.actionsRef" type="RefObject<FieldRootActions | null>">
  A ref to imperative actions.

  * `validate`: Validates the field when called.
</ParamField>

<ParamField body="Root.className" type="string | ((state: FieldRootState) => string | undefined)">
  CSS class applied to the element, or a function that
  returns a class based on the component's state.
</ParamField>

<ParamField body="Root.dirty" type="boolean">
  Whether the field's value has been changed from its initial value.
  Useful when the field state is controlled by an external library.
</ParamField>

<ParamField body="Root.disabled" type="boolean" default="false">
  Whether the component should ignore user interaction.
  Takes precedence over the `disabled` prop on the `<Field.Control>` component.
</ParamField>

<ParamField body="Root.invalid" type="boolean">
  Whether the field is invalid.
  Useful when the field state is controlled by an external library.
</ParamField>

<ParamField body="Root.name" type="string">
  Identifies the field when a form is submitted.
  Takes precedence over the `name` prop on the `<Field.Control>` component.
</ParamField>

<ParamField body="Root.render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldRootState>">
  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.
</ParamField>

<ParamField body="Root.style" type="CSSProperties | ((state: FieldRootState) => CSSProperties | undefined)">
  Style applied to the element, or a function that
  returns a style object based on the component's state.
</ParamField>

<ParamField body="Root.touched" type="boolean">
  Whether the field has been touched.
  Useful when the field state is controlled by an external library.
</ParamField>

<ParamField body="Root.validate" type="((value: unknown, formValues: Record<string, any>) => string | void | string[] | Promise<string | void | string[] | null> | 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"`.
</ParamField>

<ParamField body="Root.validationDebounceTime" type="number" default="0">
  How long to wait between `validate` callbacks if
  `validationMode="onChange"` is used. Specified in milliseconds.
</ParamField>

<ParamField body="Root.validationMode" type="&#x22;onBlur&#x22; | &#x22;onChange&#x22; | &#x22;onSubmit&#x22;" default="onSubmit">
  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.
</ParamField>

### Field.Label

<ParamField body="Label.className" type="string | ((state: FieldLabelState) => string | undefined)">
  CSS class applied to the element, or a function that
  returns a class based on the component's state.
</ParamField>

<ParamField body="Label.nativeLabel" type="boolean" default="true">
  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.
</ParamField>

<ParamField body="Label.render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldLabelState>">
  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.
</ParamField>

<ParamField body="Label.style" type="CSSProperties | ((state: FieldLabelState) => CSSProperties | undefined)">
  Style applied to the element, or a function that
  returns a style object based on the component's state.
</ParamField>

### Field.Control

<ParamField body="Control.className" type="string | ((state: FieldControlState) => string | undefined)">
  CSS class applied to the element, or a function that
  returns a class based on the component's state.
</ParamField>

<ParamField body="Control.defaultValue" type="string | number | readonly string[]" />

<ParamField body="Control.onValueChange" type="((value: string, eventDetails: { reason: &#x22;none&#x22;; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)">
  Callback fired when the `value` changes. Use when controlled.
</ParamField>

<ParamField body="Control.render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldControlState>">
  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.
</ParamField>

<ParamField body="Control.style" type="CSSProperties | ((state: FieldControlState) => CSSProperties | undefined)">
  Style applied to the element, or a function that
  returns a style object based on the component's state.
</ParamField>

### Field.Description

<ParamField body="Description.className" type="string | ((state: FieldDescriptionState) => string | undefined)">
  CSS class applied to the element, or a function that
  returns a class based on the component's state.
</ParamField>

<ParamField body="Description.render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldDescriptionState>">
  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.
</ParamField>

<ParamField body="Description.style" type="CSSProperties | ((state: FieldDescriptionState) => CSSProperties | undefined)">
  Style applied to the element, or a function that
  returns a style object based on the component's state.
</ParamField>

### Field.Error

<ParamField body="Error.className" type="string | ((state: FieldErrorState) => string | undefined)">
  CSS class applied to the element, or a function that
  returns a class based on the component's state.
</ParamField>

<ParamField body="Error.match" type="boolean | keyof ValidityState">
  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.
</ParamField>

<ParamField body="Error.render" type="ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, FieldErrorState>">
  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.
</ParamField>

<ParamField body="Error.style" type="CSSProperties | ((state: FieldErrorState) => CSSProperties | undefined)">
  Style applied to the element, or a function that
  returns a style object based on the component's state.
</ParamField>

### Field.Validity

<ParamField body="Validity.children" type="(state: FieldValidityState) => ReactNode" required>
  A function that accepts the field validity state as an argument.

  ```jsx theme={null}
  <Field.Validity>
    {(validity) => {
      return <div>...</div>
    }}
  </Field.Validity>
  ```
</ParamField>