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

> Collega un controllo di modulo alla relativa etichetta, descrizione e feedback di convalida.

## Panoramica

Usa `Field` per raggruppare un controllo con la relativa etichetta accessibile e il testo di supporto. Componenti come [Input](https://docs.twenty.com/it/ui/primitives/input/input.md) si integrano direttamente con il campo.

**Light**

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

**Dark**

[Esempio di 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)

## Utilizzo

```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` gestisce il nome del controllo, lo stato disabilitato e la validità. `Field.Label` e `Field.Description` collegano il loro contenuto al controllo. Imposta la tempistica della convalida con `validationMode`; usa `validate` per la convalida personalizzata.

## Anatomia

Inserisci un controllo e le relative parti di supporto all'interno di `Field.Root`. Questo albero mostra un campo creato con il componente `Input` stilizzato.

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

| Parte | Requisito | Scopo |
| - | - | - |
| `Root` | Obbligatorio | Condivide il nome, lo stato disabilitato e la convalida con il controllo. |
| `Item` | Facoltativo per i gruppi | Associa ogni pulsante di scelta o casella di controllo alla propria etichetta e descrizione. |
| `Label` | Consigliato | Fornisce un'etichetta visibile associata. Un nome accessibile è sempre obbligatorio. |
| `Input` o un altro controllo integrato | Obbligatorio | Riceve l'input dell'utente e si collega al campo. |
| `Control` | Controllo alternativo | Fornisce un input senza stile quando non utilizzi un controllo integrato. |
| `Description` | Facoltativo | Aggiunge testo di supporto persistente associato al controllo. |
| `Errore` | Facoltativo | Mostra feedback per uno stato di convalida corrispondente. |
| `Validity` | Facoltativo | Espone la validità tramite una funzione di rendering children. |

`Input` e `Textarea` si integrano già con il campo. Inseriscili direttamente all'interno di `Root`; forniscono autonomamente il comportamento del controllo. I controlli composti come [Select](https://docs.twenty.com/it/ui/primitives/input/select.md#compose-with-a-field) mantengono la propria radice e le proprie parti all'interno del campo.

## Errori esterni

Usa `invalid` quando la tua applicazione gestisce lo stato di errore. Un `match` esplicito rende visibile il messaggio di errore.

```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>
);
```

Mantieni i messaggi di errore orientati all'azione e fornisci un'etichetta visibile anche quando il controllo ha un segnaposto.

## Controlli raggruppati

Usa `Field.Item` all'interno di un gruppo di pulsanti di opzione o caselle di controllo per associare ogni scelta alla relativa etichetta e descrizione. Mantieni l'etichetta del gruppo al di fuori degli elementi. Un elemento può essere disabilitato indipendentemente; un `Field.Root` disabilitato disabilita ogni elemento.

**Light**

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

**Dark**

[Elementi del 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>
);
```

## Integrazione nativa e tipi

Field preserva la tempistica di convalida di Base UI, la convalida personalizzata, i valori dei controlli gestiti e non gestiti e i dettagli dell'evento di modifica del valore. `Validity` espone il risultato della convalida tramite la sua funzione children. I controlli integrati mantengono il loro comportamento nativo nei moduli.

`Root`, `Item`, `Label`, `Control`, `Description` e `Error` inoltrano props native, refs e composizione `render`. I relativi elementi predefiniti sono rispettivamente un div, div, label, input, paragrafo e div. `Validity` non esegue il rendering del proprio elemento.

Importa `FieldRootProps`, `FieldItemProps`, `FieldLabelProps`, `FieldControlProps`, `FieldDescriptionProps`, `FieldErrorProps` e `FieldValidityProps` da `twenty-ui/primitives/input` per i contratti delle parti upstream corrispondenti.

## Props

Il riferimento è generato dai tipi di componenti pubblici. Gli attributi nativi, inclusi i nomi accessibili e i gestori di eventi, sono accettati anche nelle parti che eseguono il rendering di elementi.

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