> ## 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.

# Campo

> Conecta un control de formulario con su etiqueta, descripción y comentarios de validación.

## Resumen

Usa `Field` para agrupar un control con su etiqueta accesible y texto de ayuda. Los componentes como [Input](https://docs.twenty.com/es/ui/primitives/input/input.md) se integran directamente con el campo.

**Light**

[Ejemplo de campo (light)](https://storybook.twenty.com/iframe.html?id=ui-input-field--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Ejemplo de campo (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-field--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-field--display)

## "Uso"

```tsx theme={null}
import { Field, Input } from 'twenty-ui/primitives/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` gestiona el nombre del control, el estado deshabilitado y la validez. `Field.Label` y `Field.Description` conectan su contenido con el control. Establece el momento de la validación con `validationMode`; usa `validate` para la validación personalizada.

## Anatomía

Coloque un control y sus partes de apoyo dentro de `Field.Root`. Este árbol muestra un campo creado con el componente `Input` con estilos.

```text theme={null}
Field.Root
├── Field.Label
├── Input
├── Field.Description
└── Field.Error
```

| Parte | Requisito | Propósito |
| - | - | - |
| `Root` | Obligatorio | Comparte el nombre, el estado deshabilitado y la validación con el control. |
| `Elemento` | Opcional para grupos | Asocia cada botón de opción o casilla de verificación con su propia etiqueta y descripción. |
| `Label` | Recomendado | Proporciona una etiqueta visible asociada. Siempre se requiere un nombre accesible. |
| `Input` u otro control integrado | Obligatorio | Recibe la entrada del usuario y se conecta al campo. |
| `Control` | Control alternativo | Proporciona una entrada sin estilos cuando no usa un control integrado. |
| `Description` | Opcional | Agrega texto de ayuda persistente asociado al control. |
| `Error` | Opcional | Muestra comentarios para un estado de validación coincidente. |
| `Validity` | Opcional | Expone la validez mediante una función de renderizado de elementos secundarios. |

`Input` y `Textarea` ya se integran con el campo. Colóquelos directamente dentro de `Root`; ellos mismos proporcionan el comportamiento del control. Los controles compuestos como [Select](https://docs.twenty.com/es/ui/primitives/input/select.md#compose-with-a-field) mantienen su propio elemento raíz y partes dentro del campo.

## Errores externos

Usa `invalid` cuando tu aplicación gestiona el estado de error. Un `match` explícito hace visible el mensaje de error.

```tsx theme={null}
import { Field, Input } from 'twenty-ui/primitives/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>
);
```

Mantén los mensajes de error orientados a la acción y proporciona una etiqueta visible incluso cuando el control tenga un marcador de posición.

## Controles agrupados

Use `Field.Item` dentro de un grupo de botones de opción o casillas de verificación para asociar cada opción con su propia etiqueta y descripción. Mantenga la etiqueta del grupo fuera de los elementos. Un elemento puede deshabilitarse de forma independiente; un `Field.Root` deshabilitado deshabilita todos los elementos.

**Light**

[Elementos de campo (light)](https://storybook.twenty.com/iframe.html?id=ui-input-field--grouped-items\&viewMode=story\&globals=colorScheme:light)

**Dark**

[Elementos de campo (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-field--grouped-items\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-input-field--grouped-items)

```tsx theme={null}
import { Field, Radio, RadioGroup } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const NotificationsField = () => (
  <Field.Root name="notifications">
    <Field.Label>Notifications</Field.Label>
    <RadioGroup defaultValue="important" style={{ gap: 16, marginTop: 12 }}>
      <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>
        <Radio value="important" />
        <Text>
          <Field.Label>Important updates</Field.Label>
          <Field.Description>
            Only messages that need your attention
          </Field.Description>
        </Text>
      </Field.Item>
      <Field.Item style={{ display: 'flex', alignItems: 'start', gap: 12 }}>
        <Radio value="all" />
        <Text>
          <Field.Label>All updates</Field.Label>
          <Field.Description>Every change to your records</Field.Description>
        </Text>
      </Field.Item>
      <Field.Item
        disabled
        style={{ display: 'flex', alignItems: 'start', gap: 12 }}
      >
        <Radio value="digest" />
        <Text>
          <Field.Label>Daily digest</Field.Label>
          <Field.Description>Coming soon</Field.Description>
        </Text>
      </Field.Item>
    </RadioGroup>
  </Field.Root>
);
```

## Integración nativa y tipos

Field conserva el tiempo de validación de Base UI, la validación personalizada, los valores de controles controlados y no controlados, y los detalles del evento de cambio de valor. `Validity` expone el resultado de la validación mediante su función de elementos secundarios. Los controles integrados conservan su comportamiento de formulario nativo.

`Root`, `Item`, `Label`, `Control`, `Description` y `Error` reenvían las props y refs nativas, así como la composición de `render`. Sus elementos predeterminados son un div, div, label, input, paragraph y div, respectivamente. `Validity` no representa su propio elemento.

Importe `FieldRootProps`, `FieldItemProps`, `FieldLabelProps`, `FieldControlProps`, `FieldDescriptionProps`, `FieldErrorProps` y `FieldValidityProps` desde `twenty-ui/primitives/input` para los contratos correspondientes de las partes ascendentes.

## "Props"

La referencia se genera a partir de los tipos de componentes públicos. Los atributos nativos, incluidos los nombres accesibles y los controladores de eventos, también se aceptan en las partes que renderizan elementos.

### Field.Root

**Root.actionsRef** `RefObject\<FieldRootActions | null\>`

A ref to imperative actions.

* `validate`: Validates the field when called.

**Root.className** `string | ((state: FieldRootState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Root.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.

**Root.disabled** `boolean` (default: false)

Whether the component should ignore user interaction.
Takes precedence over the `disabled` prop on the `<Field.Control>` component.

**Root.invalid** `boolean`

Whether the field is invalid.
Useful when the field state is controlled by an external library.

**Root.name** `string`

Identifies the field when a form is submitted.
Takes precedence over the `name` prop on the `<Field.Control>` component.

**Root.render** `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.

**Root.style** `CSSProperties | ((state: FieldRootState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

**Root.touched** `boolean`

Whether the field has been touched.
Useful when the field state is controlled by an external library.

**Root.validate** `((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"`.

**Root.validationDebounceTime** `number` (default: 0)

How long to wait between `validate` callbacks if
`validationMode="onChange"` is used. Specified in milliseconds.

**Root.validationMode** `"onBlur" | "onChange" | "onSubmit"` (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.

### Field.Item

**Item.className** `string | ((state: FieldItemState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Item.disabled** `boolean` (default: false)

Whether the wrapped control should ignore user interaction.
The `disabled` prop on `<Field.Root>` takes precedence over this.

**Item.render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, FieldItemState\>`

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.style** `CSSProperties | ((state: FieldItemState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Field.Label

**Label.className** `string | ((state: FieldLabelState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Label.nativeLabel** `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.

**Label.render** `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.

**Label.style** `CSSProperties | ((state: FieldLabelState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Field.Control

**Control.className** `string | ((state: FieldControlState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Control.defaultValue** `string | number | readonly string[]`

The default value of the input. Use when uncontrolled.

**Control.onValueChange** `((value: string, eventDetails: \{ reason: "none"; event: Event; cancel: () =\> void; allowPropagation: () =\> void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; \}) =\> void)`

Callback fired when the `value` changes. Use when controlled.

**Control.render** `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.

**Control.style** `CSSProperties | ((state: FieldControlState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Field.Description

**Description.className** `string | ((state: FieldDescriptionState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Description.render** `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.

**Description.style** `CSSProperties | ((state: FieldDescriptionState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Field.Error

**Error.className** `string | ((state: FieldErrorState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**Error.match** `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.

**Error.render** `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.

**Error.style** `CSSProperties | ((state: FieldErrorState) =\> CSSProperties | undefined)`

Style applied to the element, or a function that
returns a style object based on the component's state.

### Field.Validity

**Validity.children** `(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>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.