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

# Câmp

> Conectați un control de formular la eticheta, descrierea și feedbackul său de validare.

## Prezentare generală

Utilizați `Field` pentru a grupa un control cu eticheta sa accesibilă și textul ajutător. Componente precum [Input](https://docs.twenty.com/ro/ui/primitives/input/input.md) se integrează direct cu câmpul.

**Light**

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

**Dark**

[Exemplu de câmp (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)

## Utilizare

```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` gestionează numele controlului, starea de dezactivare și validitatea acestuia. `Field.Label` și `Field.Description` își conectează conținutul la control. Setați momentul validării cu `validationMode`; utilizați `validate` pentru validare personalizată.

## Anatomie internă a componentelor?

Plasați un control și componentele sale auxiliare în `Field.Root`. Această structură arată un câmp construit cu componenta stilizată `Input`.

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

| Parte | Cerință | Scop |
| - | - | - |
| `Root` | Obligatoriu | Partajează numele, starea dezactivată și validarea cu controlul. |
| `Item` | Opțional pentru grupuri | Asociază fiecărui buton radio sau fiecărei casete de selectare propria etichetă și descriere. |
| `Label` | Recomandat | Furnizează o etichetă vizibilă asociată. Este întotdeauna necesar un nume accesibil. |
| `Input` sau un alt control integrat | Obligatoriu | Primește datele introduse de utilizator și se conectează la câmp. |
| `Control` | Control alternativ | Furnizează o intrare nestilizată atunci când nu utilizați un control integrat. |
| `Description` | Opțional | Adaugă text de ajutor persistent asociat cu controlul. |
| `Eroare` | Opțional | Afișează feedback pentru o stare de validare corespunzătoare. |
| `Validity` | Opțional | Expune validitatea printr-o funcție de randare pentru copii. |

`Input` și `Textarea` se integrează deja cu câmpul. Plasați-le direct în `Root`; acestea furnizează singure comportamentul de control. Controalele compuse, precum [Select](https://docs.twenty.com/ro/ui/primitives/input/select.md#compose-with-a-field), își păstrează propria rădăcină și propriile componente în interiorul câmpului.

## Erori externe

Utilizați `invalid` atunci când aplicația dvs. gestionează starea de eroare. Un `match` explicit face vizibil mesajul de eroare.

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

Păstrați mesajele de eroare ușor de acționat și oferiți o etichetă vizibilă chiar și atunci când controlul are un substituent.

## Controale grupate

Folosește `Field.Item` într-un grup de butoane radio sau de casete de selectare pentru a asocia fiecare opțiune cu propria etichetă și descriere. Păstrează eticheta grupului în afara elementelor. Un element poate fi dezactivat independent; un `Field.Root` dezactivat dezactivează fiecare element.

**Light**

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

**Dark**

[Elemente de câmp (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>
);
```

## Integrare nativă și tipuri

Field păstrează momentul validării Base UI, validarea personalizată, valorile controlate și necontrolate ale controalelor și detaliile evenimentului de modificare a valorii. `Validity` expune rezultatul validării prin funcția sa children. Controalele integrate își păstrează comportamentul nativ al formularului.

`Root`, `Item`, `Label`, `Control`, `Description` și `Error` transmit props native, refs și compoziția `render`. Elementele lor implicite sunt, respectiv, un div, div, label, input, paragraf și div. `Validity` nu redă propriul element.

Importă `FieldRootProps`, `FieldItemProps`, `FieldLabelProps`, `FieldControlProps`, `FieldDescriptionProps`, `FieldErrorProps` și `FieldValidityProps` din `twenty-ui/primitives/input` pentru contractele corespunzătoare ale componentelor din amonte.

## Proprietăți

Referința este generată din tipurile componentei publice. Atributele native, inclusiv numele accesibile și gestionarele de evenimente, sunt acceptate și pe părțile care redau elemente.

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