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

# مربع اختيار

> حدّد خيارات مستقلة بحالات محددة وغير محددة وحالة غير محسومة.

## نظرة عامة

استخدم `Checkbox` عندما يمكن تحديد كل خيار بشكل مستقل. للاختيار المتبادل الحصري، استخدم [RadioGroup](https://docs.twenty.com/ar/ui/primitives/input/radio-group.md).

**Light**

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

**Dark**

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

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

## استخدام

### الحالة غير المتحكم بها

استخدم `defaultChecked` لتعيين حالة التحديد الأولية. يمتلك مربع الاختيار التغييرات اللاحقة.

```tsx theme={null}
import { useId } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const EmailPreference = () => {
  const checkboxId = useId();

  return (
    <label
      htmlFor={checkboxId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Checkbox id={checkboxId} name="updates" value="email" defaultChecked />
      <Text render={<span />}>Receive product updates</Text>
    </label>
  );
};
```

يساهم مربع اختيار محدد ومسمى بقيمته في نموذج. عيّن `uncheckedValue` إذا كان ينبغي للنموذج أيضًا إرسال قيمة عندما يكون غير محدد.

## المظهر والتفاعل

قارن بين حالات المحدد وغير المحدد والمعطل، ثم اختر اللون والحجم والشكل والمتغير بشكل مستقل. يمكن تبديل الأمثلة المفعلة.

**Light**

[المظهر والتفاعل لمربع الاختيار (light)](https://storybook.twenty.com/iframe.html?id=ui-input-checkbox-checkbox--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[المظهر والتفاعل لمربع الاختيار (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-checkbox-checkbox--catalog\&viewMode=story\&globals=colorScheme:dark)

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

| الخاصية | القيم | الإعداد الافتراضي |
| - | - | - |
| `الحجم` | `sm`, `md` | `sm` |
| `variant` | `solid`, `outline`, `soft` | `solid` |
| `shape` | `square`, `round` | `square` |
| `اللون` | `accent`, `success`, `warning` | `accent` |

يركّز مفتاح Tab على مربع الاختيار، ويبدّل مفتاح Space حالته. يؤدي النقر على تسميته أيضًا إلى تبديل حالته. استخدم `disabled` لمنع التفاعل، أو `readOnly` عندما ينبغي أن تبقى القيمة دون تغيير مع بقاء عنصر التحكم قابلاً للتركيز. أبقِ المعنى في التسمية بدلًا من إيصاله عبر اللون وحده.

## الحالة المتحكَّم بها

مرّر `checked` وحدّثه باستخدام `onCheckedChange` لامتلاك التفضيل نفسه في حالة React. تتلقى دالة الاستدعاء القيمة المنطقية التالية وتفاصيل الحدث.

```tsx theme={null}
import { useId, useState } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';
import { Text } from 'twenty-ui/primitives/typography';

export const EmailPreference = () => {
  const checkboxId = useId();
  const [checked, setChecked] = useState(true);

  return (
    <label
      htmlFor={checkboxId}
      style={{ display: 'inline-flex', alignItems: 'center', gap: 8 }}
    >
      <Checkbox
        id={checkboxId}
        name="updates"
        value="email"
        checked={checked}
        onCheckedChange={setChecked}
      />
      <Text render={<span />}>Receive product updates</Text>
    </label>
  );
};
```

## حالة غير محددة

يمثل مربع الاختيار غير المحدد اختيارًا جزئيًا. اشتقه من الخيارات الفرعية بشكل مستقل عن حالة تحديد مربع الاختيار.

```tsx theme={null}
import { useState } from 'react';
import { Checkbox } from 'twenty-ui/primitives/input';

export const ColumnSelection = () => {
  const [showEmail, setShowEmail] = useState(true);
  const [showPhone, setShowPhone] = useState(false);

  return (
    <fieldset>
      <legend>Visible columns</legend>
      <label>
        <Checkbox
          checked={showEmail && showPhone}
          indeterminate={showEmail !== showPhone}
          onCheckedChange={(checked) => {
            setShowEmail(checked);
            setShowPhone(checked);
          }}
        />
        All columns
      </label>
      <label>
        <Checkbox checked={showEmail} onCheckedChange={setShowEmail} />
        Email
      </label>
      <label>
        <Checkbox checked={showPhone} onCheckedChange={setShowPhone} />
        Phone
      </label>
    </fieldset>
  );
};
```

## الأجزاء والمحتوى المخصص

يجمع `Checkbox` الجذر المنسق وأيقونتي التحديد والحالة غير المحددة الافتراضيتين. استخدم `Checkbox.Root` مع `Checkbox.Indicator` لتتولى ملكية محتوى المؤشر. يتولى الجذر الحالة ومظهر المربع؛ ويعرض المؤشر المحتوى الذي توفره.

```tsx theme={null}
import { IconCheck } from 'twenty-ui/icon';
import { Checkbox } from 'twenty-ui/primitives/input';

export const CustomPreference = () => (
  <Checkbox.Root aria-label="Updates" defaultChecked>
    <Checkbox.Indicator>
      <IconCheck aria-hidden />
    </Checkbox.Indicator>
  </Checkbox.Root>
);
```

`CheckboxRootProps` و`CheckboxIndicatorProps` نوعان عامان مُصدَّران من `twenty-ui/primitives/input`. يقبل كلا الجزأين السمات الأصلية والمعالجات والمراجع و`render` واستدعاءات `className` و`style` المعتمدة على الحالة. يستهدف `ref` الخاص بالجذر عنصر التحكم المرئي؛ ويستهدف `inputRef` الإدخال الأصلي. يستهدف مرجع الجزء العنصر الذي يعرضه. مرر `nativeButton` مع `render={<button />}` عند استبدال الجذر بزر. تنتمي خصائص المظهر إلى الجذر؛ وتُدمج الفئات والأنماط الصريحة مع الإعدادات الافتراضية.

يتلقى المؤشر حالة التحديد والحالة غير المحددة، بما في ذلك حالة الانتقال. عيّن `keepMounted` للاحتفاظ بمؤشر غير محدد في DOM؛ إذ يخفيه التنسيق الافتراضي باستخدام العتامة. تجاوز `style` أو `className` الخاص به لإجراء انتقالات مخصصة.

**Light**

[تركيب أجزاء Checkbox (light)](https://storybook.twenty.com/iframe.html?id=ui-input-checkbox-parts--composition\&viewMode=story\&globals=colorScheme:light)

**Dark**

[تركيب أجزاء Checkbox (dark)](https://storybook.twenty.com/iframe.html?id=ui-input-checkbox-parts--composition\&viewMode=story\&globals=colorScheme:dark)

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

يبقى التجميع القابل للاستدعاء ونوعه `CheckboxProps` مدعومين. استبدل التجميع بالجذر وجزئه عند توفير أيقونات مخصصة بدلاً من إلحاق جزء آخر بأبناء التجميع.

لإعادة تعيين نموذج متحكم به، عالج `onReset` الخاص بالنموذج وأعد `checked` إلى قيمتك الأولية. لا يستعيد Base UI 1.8 حالة المكوّن غير المتحكم به عند إعادة تعيين النموذج الأصلية. تحافظ `required` و`form` و`value` و`uncheckedValue` على سلوك الإدخال الأصلي في المصدر.

## الإزاحة

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

**checked** `boolean`

Whether the checkbox is currently ticked.

To render an uncontrolled checkbox, use the `defaultChecked` prop instead.

**className** `string | ((state: CheckboxRootState) =\> string | undefined)`

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

**color** `"accent" | "success" | "warning"` (default: accent)

Color used while the checkbox is checked or indeterminate.

**defaultChecked** `boolean` (default: false)

Whether the checkbox is initially ticked.

To render a controlled checkbox, use the `checked` prop instead.

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

Whether the component should ignore user interaction.

**form** `string`

Identifies the form that owns the hidden input.
Useful when the checkbox is rendered outside the form.

**hoverable** `boolean` (default: true)

Adds padding and a hover background around the box.

**id** `string`

The id of the input element.

**indeterminate** `boolean` (default: false)

Whether the checkbox is in a mixed state: neither ticked, nor unticked.

**inputRef** `Ref\<HTMLInputElement\>`

A ref to access the hidden `<input>` element.

**name** `string`

Identifies the field when a form is submitted.

**nativeButton** `boolean` (default: false)

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `true` if the rendered element is a native button.

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

Event handler called when the checkbox is ticked or unticked.

**parent** `boolean` (default: false)

Whether the checkbox controls a group of child checkboxes.

Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).

**readOnly** `boolean` (default: false)

Whether the user should be unable to tick or untick the checkbox.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, CheckboxRootState\>`

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.

**required** `boolean` (default: false)

Whether the user must tick the checkbox before submitting a form.

**shape** `"round" | "square"` (default: square)

Corner shape of the box.

**size** `"md" | "sm"` (default: sm)

Visual size of the checkbox.

**style** `CSSProperties | ((state: CheckboxRootState) =\> CSSProperties | undefined)`

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

**uncheckedValue** `string`

The value submitted with the form when the checkbox is unchecked.
By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.

**value** `string`

The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".

**variant** `"outline" | "soft" | "solid"` (default: solid)

Visual style of the box: filled, outlined, or tinted.

### Checkbox.Root

**Root.checked** `boolean`

Whether the checkbox is currently ticked.

To render an uncontrolled checkbox, use the `defaultChecked` prop instead.

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

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

**Root.color** `"accent" | "success" | "warning"` (default: accent)

Color used while the checkbox is checked or indeterminate.

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

Whether the checkbox is initially ticked.

To render a controlled checkbox, use the `checked` prop instead.

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

Whether the component should ignore user interaction.

**Root.form** `string`

Identifies the form that owns the hidden input.
Useful when the checkbox is rendered outside the form.

**Root.hoverable** `boolean` (default: true)

Adds padding and a hover background around the box.

**Root.id** `string`

The id of the input element.

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

Whether the checkbox is in a mixed state: neither ticked, nor unticked.

**Root.inputRef** `Ref\<HTMLInputElement\>`

A ref to access the hidden `<input>` element.

**Root.name** `string`

Identifies the field when a form is submitted.

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

Whether the component renders a native `<button>` element when replacing it
via the `render` prop.
Set to `true` if the rendered element is a native button.

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

Event handler called when the checkbox is ticked or unticked.

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

Whether the checkbox controls a group of child checkboxes.

Must be used in a [Checkbox Group](https://base-ui.com/react/components/checkbox-group).

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

Whether the user should be unable to tick or untick the checkbox.

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

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.required** `boolean` (default: false)

Whether the user must tick the checkbox before submitting a form.

**Root.shape** `"round" | "square"` (default: square)

Corner shape of the box.

**Root.size** `"md" | "sm"` (default: sm)

Visual size of the checkbox.

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

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

**Root.uncheckedValue** `string`

The value submitted with the form when the checkbox is unchecked.
By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.

**Root.value** `string`

The checkbox's value. Identifies it within a [Checkbox Group](https://base-ui.com/react/components/checkbox-group), falling back to `name` when omitted.
When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".

**Root.variant** `"outline" | "soft" | "solid"` (default: solid)

Visual style of the box: filled, outlined, or tinted.

### Checkbox.Indicator

**Indicator.className** `string | ((state: CheckboxIndicatorState) =\> string | undefined)`

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

**Indicator.keepMounted** `boolean` (default: false)

Whether to keep the element in the DOM when the checkbox is not checked.

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

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.

**Indicator.style** `CSSProperties | ((state: CheckboxIndicatorState) =\> CSSProperties | undefined)`

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


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