Checkbox
مربع لاختيار نعم/لا، أو لاختيار عدة خيارات. أساسي ومحايد، وثلاثة أحجام، ومحدد وجزئي وللقراءة فقط ومعطّل وخطأ.
الإصدار 0.4.1 ·
التثبيت
bunx --bun shadcn@latest add @dga/checkboxويثبّت Field أيضًا.
الاستخدام
import { Checkbox } from "@/components/ui/checkbox";
import { Field, FieldContent, FieldLabel } from "@/components/ui/field";
export function ConsentField() {
return (
<Field orientation="horizontal" name="consent">
<Checkbox required />
<FieldContent>
<FieldLabel>أقرّ بأن المعلومات صحيحة</FieldLabel>
</FieldContent>
</Field>
);
}استخدم Checkbox عندما يمكن للمستخدم ألا يختار شيئًا أو يختار خيارًا أو عدة خيارات، أو يقرّ بشيء قبل الإرسال. يُطبَّق الاختيار عند إرسال النموذج؛ وللإعداد الذي يسري فورًا استخدم Switch. ولاختيار واحد فقط من عدة خيارات استخدم Radio.
البنية
- المربع (
<span role="checkbox">مع<input>مخفي): الحد والتعبئة. - العلامة: علامة صح، أو شرطة عند الحالة الجزئية.
- التسمية والنص المساعد والخطأ: من Field، بجانب المربع.
أمثلة
الحالات
غير محدد ومحدد وجزئي وللقراءة فقط ومعطّل وخطأ والنمط المحايد.
الأحجام
md بحجم 24px (الافتراضي)، وsm بحجم 20px، وxs بحجم 16px. والتسمية، لا المربع، هي هدف النقر، فيبقى مريحًا في كل الأحجام.
مجموعة مع عنصر أب
اضبط indeterminate على العنصر الأب عندما يكون بعض الأبناء فقط محددًا. ويحدد الأب كل الأبناء أو يلغي تحديدهم.
RTL
يقع المربع على يمين (بداية) تسميته، ويصطف النص المساعد تحت التسمية. وعلامة الصح غير اتجاهية فلا تُعكس.
إمكانية الوصول
| المفتاح | الإجراء |
|---|---|
| Tab | ينقل التركيز إلى مربع الاختيار. |
| Space | يحدده أو يلغي تحديده. |
- الدور
checkboxمعaria-checked(trueأوfalseأوmixed)، وحقل أصلي مخفي للنماذج. - تأتي التسمية من Field؛ والنقر عليها يبدّل المربع.
- حد المربع غير المحدد بنسبة 3:1 أو أفضل على كل سطح؛ وتعبئة المربع المحدد وعلامته بنسبة 3:1 مقابل السطح ومقابل بعضهما (WCAG 1.4.11).
- التركيز حد بسمك 2px على بعد 2px خارج المربع. وللقراءة فقط حد بنسبة 3:1.
- يعرض الخطأ أيقونة ونصًا مع
aria-invalid، لا تغيّر لون وحده.
مرجع API
Checkbox
مربع لاختيار نعم/لا، أو لاختيار واحد من عدة خيارات. `indeterminate` يعرض شرطة لعنصر أب اختير بعض أبنائه فقط. سمّه بـ Field (`orientation="horizontal"`) أو بتسمية تحيط به.
| الخاصية | النوع | القيمة الافتراضية |
|---|---|---|
"xs" | "sm" | "md"حجم المربع: `md` 24px، و`sm` 20px، و`xs` 16px. | "md" | |
| ||
"primary" | "neutral"`primary` (أخضر) أو `neutral` (أسود في الوضع الفاتح). | "primary" | |
| ||
booleanيعرض شرطة ويُبلّغ بـ `aria-checked=mixed`، لعنصر أب اختير بعض أبنائه فقط. | لا توجد قيمة افتراضية | |
| ||
booleanحالة متحكَّم بها. | لا توجد قيمة افتراضية | |
| ||
booleanالحالة الابتدائية عند عدم التحكم. | لا توجد قيمة افتراضية | |
| ||
booleanيعطّل المربع. | لا توجد قيمة افتراضية | |
| ||
stringاسم الحقل عند إرسال النموذج. | لا توجد قيمة افتراضية | |
| ||
(checked: boolean, details) => voidتُستدعى عند تبديل المستخدم المربع. من Base UI. | لا توجد قيمة افتراضية | |
| ||
booleanيعرض الحالة دون إمكانية تغييرها. | لا توجد قيمة افتراضية | |
| ||
booleanلا يمكن إرسال النموذج قبل تحديده. | لا توجد قيمة افتراضية | |
| ||
stringالقيمة التي تُرسل عند التحديد. | لا توجد قيمة افتراضية | |
| ||
يقبل أيضًا جميع خصائص Base UI Checkbox (يفتح في نافذة جديدة).
الاختلافات عن DGA
- في الوضع الداكن تبقى تعبئة المربع المحدد green-600 عند التمرير والضغط، لأن الخضرة الأفتح في Figma تعطي العلامة البيضاء 1.4–2.1:1.
- تنقلب علامة الصح المحايدة مع التعبئة (رمز جديد
control-icon-neutral). - للقراءة فقط حد بنسبة 3:1 (في Figma: 1.5:1).
| التغيير | السبب |
|---|---|
--control-primary-hovered (dark) و1 غيرها | Figma Dark lightens the checked fill on hover and press (green-300/400). The white check mark on it is 1.4–2.1:1. The fill stays green-600 and hover and press show on the ring and background instead. |
--control-icon-neutral (new) | The check mark on a neutral checkbox. The neutral fill is near-black in light mode and light grey in dark mode (control-neutral-checked), so the mark needs to flip too. Figma's control-icon-* tokens stay white (1.8:1 on the dark-mode fill). |
Checkbox, Radio: hover and pressed fill in dark mode | A white mark on the lighter fill is 1.4–2.1:1 (see the control-primary-hovered and -pressed fixes). |
Checkbox, Radio, Switch: read-only | The pale border is 1.5:1 on white. A read-only control keeps a 3:1 boundary. |
عرض جميع الاختلافات (6) لهذا المكوّن أسباب الاختلافات مكتوبة بالإنجليزية.
التباين
108 زوجًا لونيًا فُحص · جميعها تجتاز WCAG 2.1 AAعرض 20 حالةإخفاء
| النمط / الحالة | الفاتح | الداكن |
|---|---|---|
| unchecked border | 4.57:1 3:1 | 3.80:1 3:1 |
| unchecked border, hovered | 7.04:1 3:1 | 12.04:1 3:1 |
| border, error | 4.62:1 3:1 | 4.65:1 3:1 |
| border, read-only | 4.57:1 3:1 | 3.80:1 3:1 |
| focus ring | 17.31:1 3:1 | 17.49:1 3:1 |
| primary / checked (fill) | 4.54:1 3:1 | 3.68:1 3:1 |
| primary / checked (check mark) | 4.74:1 3:1 | 4.74:1 3:1 |
| primary / hovered (fill) | 8.18:1 3:1 | 3.68:1 3:1 |
| primary / hovered (check mark) | 8.55:1 3:1 | 4.74:1 3:1 |
| primary / pressed (fill) | 10.34:1 3:1 | 3.68:1 3:1 |
| primary / pressed (check mark) | 10.81:1 3:1 | 4.74:1 3:1 |
| neutral / checked (fill) | 17.93:1 3:1 | 9.38:1 3:1 |
| neutral / checked (check mark) | 18.74:1 3:1 | 10.07:1 3:1 |
| neutral / hovered (fill) | 7.04:1 3:1 | 12.04:1 3:1 |
| neutral / hovered (check mark) | 7.36:1 3:1 | 12.93:1 3:1 |
| neutral / pressed (fill) | 4.57:1 3:1 | 6.32:1 3:1 |
| neutral / pressed (check mark) | 4.77:1 3:1 | 6.79:1 3:1 |
| read-only mark | 4.77:1 3:1 | 9.38:1 3:1 |
| label | 14.53:1 AAA | 15.87:1 AAA |
| helper text | 4.77:1 AA | 6.32:1 AA |
يحتاج النص إلى تباين 4.5:1، والأيقونات وحلقات التركيز إلى 3:1. الحالات المعطّلة مستثناة. تقرير التباين الكامل