> ## 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` لتجميع عنصر تحكم واحد مع تسميته القابلة للوصول ونصه المساعد. تتكامل مكونات مثل [Input](https://docs.twenty.com/ar/ui/primitives/input/input.md) مباشرةً مع الحقل.

**Light**

[مثال على Field (light)](https://storybook.twenty.com/iframe.html?id=ui-input-field--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مثال على Field (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)

## استخدام

```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` اسم عنصر التحكم وحالة تعطيله وصلاحيته. يربط `Field.Label` و`Field.Description` محتواهما بعنصر التحكم. عيّن توقيت التحقق باستخدام `validationMode`؛ واستخدم `validate` للتحقق المخصص.

## البنية التشريحية العربية

ضع عنصر تحكم واحدًا وأجزاءه الداعمة داخل `Field.Root`. تُظهر هذه الشجرة حقلًا مُنشأ باستخدام المكوّن `Input` المنسّق.

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

| الجزء | المتطلبة | الغرض |
| - | - | - |
| `Root` | مطلوب | يشارك الاسم وحالة التعطيل والتحقق مع عنصر التحكم. |
| `Item` | اختياري للمجموعات | يربط كل زر اختيار أو مربع اختيار بتسميته ووصفه الخاصين. |
| `Label` | مُوصى به | يوفّر تسمية مرئية ومرتبطة. يلزم دائمًا اسم يمكن الوصول إليه. |
| `Input` أو عنصر تحكم متكامل آخر | مطلوب | يتلقى إدخال المستخدم ويتصل بالحقل. |
| `Control` | عنصر تحكم بديل | يوفّر إدخالًا بلا تنسيق عندما لا تستخدم عنصر تحكم متكاملًا. |
| `Description` | اختياري | يضيف نص مساعدة دائمًا مرتبطًا بعنصر التحكم. |
| `خطأ` | اختياري | يعرض ملاحظات لحالة تحقق مطابقة. |
| `Validity` | اختياري | يكشف عن الصلاحية عبر دالة تصيير الأبناء. |

يتكامل `Input` و`Textarea` بالفعل مع الحقل. ضعهما مباشرةً داخل `Root`؛ فهما يوفّران سلوك عنصر التحكم بنفسيهما. تحتفظ عناصر التحكم المركّبة، مثل [تحديد](https://docs.twenty.com/ar/ui/primitives/input/select.md#compose-with-a-field)، بجذرها وأجزائها الخاصة داخل الحقل.

## أخطاء خارجية

استخدم `invalid` عندما يكون تطبيقك مسؤولًا عن حالة الخطأ. يجعل `match` الصريح رسالة الخطأ مرئية.

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

اجعل رسائل الخطأ قابلة للتنفيذ وقدّم تسمية مرئية حتى عندما يحتوي عنصر التحكم على نص نائب.

## عناصر التحكم المجمّعة

استخدم `Field.Item` داخل مجموعة أزرار اختيار أو مربعات اختيار لربط كل خيار بتسمية ووصف خاصين به. أبقِ تسمية المجموعة خارج العناصر. يمكن تعطيل عنصر بشكل مستقل؛ إذ يعطّل `Field.Root` المعطّل كل عنصر.

**Light**

[عناصر الحقل (light)](https://storybook.twenty.com/iframe.html?id=ui-input-field--grouped-items\&viewMode=story\&globals=colorScheme:light)

**Dark**

[عناصر الحقل (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>
);
```

## التكامل والأنواع الأصلية

يحافظ الحقل على توقيت التحقق في Base UI، والتحقق المخصص، وقيم عناصر التحكم المُتحكَّم بها وغير المُتحكَّم بها، وتفاصيل حدث تغيير القيمة. يكشف `Validity` عن نتيجة التحقق من خلال دالة الأبناء الخاصة به. تحتفظ عناصر التحكم المتكاملة بسلوك النموذج الأصلي الخاص بها.

تمرّر `Root` و`Item` و`Label` و`Control` و`Description` و`Error` الخصائص الأصلية والمراجع وتكوين `render`. عناصرها الافتراضية هي div وdiv وlabel وinput وparagraph وdiv، على التوالي. لا يعرض `Validity` عنصره الخاص.

استورد `FieldRootProps` و`FieldItemProps` و`FieldLabelProps` و`FieldControlProps` و`FieldDescriptionProps` و`FieldErrorProps` و`FieldValidityProps` من `twenty-ui/primitives/input` لعقود الأجزاء الأساسية المقابلة.

## الإزاحة

يُنشأ المرجع من الأنواع العامة للمكونات. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء القابلة للوصول ومعالجات الأحداث، على الأجزاء التي تصيّر عناصر.

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