الانتقال إلى المحتوى الرئيسي

نظرة عامة

استخدم Checkbox عندما يمكن تحديد كل خيار بشكل مستقل. للاختيار المتبادل الحصري، استخدم RadioGroup.

استخدام

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

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

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

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

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

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

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

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

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

يجمع Checkbox الجذر المنسق وأيقونتي التحديد والحالة غير المحددة الافتراضيتين. استخدم Checkbox.Root مع Checkbox.Indicator لتتولى ملكية محتوى المؤشر. يتولى الجذر الحالة ومظهر المربع؛ ويعرض المؤشر المحتوى الذي توفره.
CheckboxRootProps وCheckboxIndicatorProps نوعان عامان مُصدَّران من twenty-ui/primitives/input. يقبل كلا الجزأين السمات الأصلية والمعالجات والمراجع وrender واستدعاءات className وstyle المعتمدة على الحالة. يستهدف ref الخاص بالجذر عنصر التحكم المرئي؛ ويستهدف inputRef الإدخال الأصلي. يستهدف مرجع الجزء العنصر الذي يعرضه. مرر nativeButton مع render={<button />} عند استبدال الجذر بزر. تنتمي خصائص المظهر إلى الجذر؛ وتُدمج الفئات والأنماط الصريحة مع الإعدادات الافتراضية. يتلقى المؤشر حالة التحديد والحالة غير المحددة، بما في ذلك حالة الانتقال. عيّن keepMounted للاحتفاظ بمؤشر غير محدد في DOM؛ إذ يخفيه التنسيق الافتراضي باستخدام العتامة. تجاوز style أو className الخاص به لإجراء انتقالات مخصصة. يبقى التجميع القابل للاستدعاء ونوعه CheckboxProps مدعومين. استبدل التجميع بالجذر وجزئه عند توفير أيقونات مخصصة بدلاً من إلحاق جزء آخر بأبناء التجميع. لإعادة تعيين نموذج متحكم به، عالج onReset الخاص بالنموذج وأعد checked إلى قيمتك الأولية. لا يستعيد Base UI 1.8 حالة المكوّن غير المتحكم به عند إعادة تعيين النموذج الأصلية. تحافظ required وform وvalue وuncheckedValue على سلوك الإدخال الأصلي في المصدر.

الإزاحة

يتم إنشاء المرجع من أنواع المكونات العامة. تُقبل أيضًا السمات الأصلية، بما في ذلك الأسماء المتاحة ومعالجات الأحداث، على الأجزاء التي تعرض عناصر.
boolean
Whether the checkbox is currently ticked.To render an uncontrolled checkbox, use the defaultChecked prop instead.
string | ((state: CheckboxRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "success" | "warning"
افتراضي:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
افتراضي:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the checked prop instead.
boolean
افتراضي:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
boolean
افتراضي:"true"
Adds padding and a hover background around the box.
string
The id of the input element.
boolean
افتراضي:"false"
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
string
Identifies the field when a form is submitted.
boolean
افتراضي:"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.
((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.
boolean
افتراضي:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
افتراضي:"false"
Whether the user should be unable to tick or untick the checkbox.
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.
boolean
افتراضي:"false"
Whether the user must tick the checkbox before submitting a form.
"round" | "square"
افتراضي:"square"
Corner shape of the box.
"md" | "sm"
افتراضي:"sm"
Visual size of the checkbox.
CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
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.
string
The checkbox’s value. Identifies it within a 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”.
"outline" | "soft" | "solid"
افتراضي:"solid"
Visual style of the box: filled, outlined, or tinted.

Checkbox.Root

boolean
Whether the checkbox is currently ticked.To render an uncontrolled checkbox, use the defaultChecked prop instead.
string | ((state: CheckboxRootState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
"accent" | "success" | "warning"
افتراضي:"accent"
Color used while the checkbox is checked or indeterminate.
boolean
افتراضي:"false"
Whether the checkbox is initially ticked.To render a controlled checkbox, use the checked prop instead.
boolean
افتراضي:"false"
Whether the component should ignore user interaction.
string
Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
boolean
افتراضي:"true"
Adds padding and a hover background around the box.
string
The id of the input element.
boolean
افتراضي:"false"
Whether the checkbox is in a mixed state: neither ticked, nor unticked.
Ref<HTMLInputElement>
A ref to access the hidden <input> element.
string
Identifies the field when a form is submitted.
boolean
افتراضي:"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.
((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.
boolean
افتراضي:"false"
Whether the checkbox controls a group of child checkboxes.Must be used in a Checkbox Group.
boolean
افتراضي:"false"
Whether the user should be unable to tick or untick the checkbox.
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.
boolean
افتراضي:"false"
Whether the user must tick the checkbox before submitting a form.
"round" | "square"
افتراضي:"square"
Corner shape of the box.
"md" | "sm"
افتراضي:"sm"
Visual size of the checkbox.
CSSProperties | ((state: CheckboxRootState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.
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.
string
The checkbox’s value. Identifies it within a 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”.
"outline" | "soft" | "solid"
افتراضي:"solid"
Visual style of the box: filled, outlined, or tinted.

Checkbox.Indicator

string | ((state: CheckboxIndicatorState) => string | undefined)
CSS class applied to the element, or a function that returns a class based on the component’s state.
boolean
افتراضي:"false"
Whether to keep the element in the DOM when the checkbox is not checked.
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.
CSSProperties | ((state: CheckboxIndicatorState) => CSSProperties | undefined)
Style applied to the element, or a function that returns a style object based on the component’s state.