Checkboxv1.0.1
برای تایید یک شرط یا انتخاب چند گزینه از یک فهرست، با پشتیبانی کامل از فوکوس و صفحه‌کلید.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/checkbox.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/checkbox.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/checkbox.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/checkbox.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Checkbox } from "@/components/ui/checkbox"
import { Label } from "@/components/ui/label"
<Checkbox id="terms" />
<Label htmlFor="terms">با قوانین و مقررات موافقم</Label>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
برای هماهنگ‌کردن چند چک‌باکس با یک آرایهٔ مقادیر انتخاب‌شده (به‌جای چند boolean جدا)، از CheckboxGroup استفاده کنید: به هر Checkbox داخلش یک value بدهید تا خودش را عضو گروه بداند؛ disabled/invalid/required روی خودِ گروه به‌صورت پیش‌فرض به همهٔ فرزندان می‌رسد.
دسترس‌پذیری
- فعال‌سازی با کلید Space و نقش checkbox به‌صورت پیش‌فرض تنظیم است.
- برای وضعیت نامشخص (indeterminate) مقدار checked="indeterminate" را پاس دهید.
- با Label و htmlFor، برچسب برای صفحه‌خوان و کلیک‌پذیری ناحیهٔ بزرگ‌تر فراهم می‌شود.
- readOnly برخلاف disabled، چک‌باکس را از چرخهٔ Tab و صفحه‌خوان حذف نمی‌کند؛ فقط جلوی تغییر مقدار را می‌گیرد.
- invalid مقدار aria-invalid را ست می‌کند تا صفحه‌خوان وضعیت نامعتبر را همراه با متن خطای کنارش اعلام کند.
- CheckboxGroup نقش group می‌گیرد و aria-required/aria-invalid آن به کل مجموعه اشاره می‌کند، نه یک گزینهٔ خاص.
مرجع API
Checkbox
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| checked | boolean | "indeterminate" | — | وضعیت کنترل‌شده (controlled) چک‌باکس. |
| defaultChecked | boolean | "indeterminate" | false | وضعیت اولیهٔ چک‌باکس در حالت کنترل‌نشده. |
| onCheckedChange | (checked: boolean | "indeterminate") => void | — | فراخوانی هنگام تغییر وضعیت. |
| variant | "default" | "flat" | "default" | default سایه‌دار است؛ flat بدون سایه و با پس‌زمینهٔ خاکستری خنثی، برای داخل کارت یا Surface. |
| interaction | "none" | "press" | "pop" | "peek" | "draw" | "none" | واکنش به فشردن و هاور: press کوچک شدن هنگام فشردن، pop ظاهر شدن علامت با جهش، peek پیش‌نمایش علامت روی هاور. روی disabled و readOnly اعمال نمی‌شود. بدون مقدار، از CheckboxGroup ارث می‌برد. |
| disabled | boolean | false | غیرفعال می‌کند و از چرخهٔ Tab خارج می‌کند؛ ظاهر کم‌رنگ می‌شود. |
| readOnly | boolean | false | برخلاف disabled، در چرخهٔ Tab می‌ماند و ظاهر عادی دارد؛ فقط تغییر مقدار را می‌گیرد. |
| invalid | boolean | false | وضعیت نامعتبر برای فرم‌ها؛ aria-invalid و رنگ خطا (قرمز) را روشن می‌کند. |
| required | boolean | false | aria-required روی چک‌باکس می‌گذارد. |
| value | string | — | فقط داخل CheckboxGroup معنا دارد: مقدار این گزینه در آرایهٔ انتخاب‌شده‌ها. |
CheckboxGroup
چند Checkbox را با یک آرایهٔ مقادیر انتخاب‌شده هماهنگ می‌کند؛ خودش نقش group می‌گیرد.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string[] | — | آرایهٔ مقادیر انتخاب‌شده (کنترل‌شده). |
| defaultValue | string[] | [] | آرایهٔ مقادیر اولیه در حالت کنترل‌نشده. |
| onValueChange | (value: string[]) => void | — | با هر بار افزوده یا حذف‌شدن یک مقدار صدا زده می‌شود. |
| interaction | "none" | "press" | "pop" | "peek" | "draw" | "none" | اینتراکشن پیش‌فرض همهٔ چک‌باکس‌های داخل گروه. |
| disabled | boolean | false | پیش‌فرض همهٔ فرزندان را غیرفعال می‌کند؛ هر Checkbox می‌تواند با disabled={false} این را نادیده بگیرد. |
| invalid | boolean | false | پیش‌فرض همهٔ فرزندان را در حالت نامعتبر نشان می‌دهد. |
| required | boolean | false | aria-required روی نقش group می‌گذارد. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
اینتراکشن (interaction)
واکنش چک‌باکس به فشردن و هاور. press برای فرم‌های پرتکرار کافی است؛ pop تیک را با جهش و یک ضربه به جعبه نشان می‌دهد؛ peek روی هاور تیک را پیش‌نمایش می‌کند؛ draw تیک را مثل قلم می‌کشد. دموها خودشان روشن و خاموش می‌شوند تا فرق حرکت دیده شود. روی CheckboxGroup یک بار بدهید تا به همه برسد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نامعتبر (Invalid)
برای خطای اعتبارسنجی فرم، invalid بدهید؛ حاشیه قرمز می‌شود و در حالت انتخاب‌شده، رنگ داخل باکس هم به‌جای primary قرمز می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
فقط‌خواندنی (Read-only)
برخلاف disabled، readOnly ظاهر عادی را حفظ می‌کند و در چرخهٔ Tab می‌ماند؛ فقط جلوی تغییر مقدار با کلیک یا کیبورد را می‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Variant: default و flat
variant="flat" سایه ندارد و پس‌زمینهٔ خاکستری خنثی می‌گیرد، برای وقتی چک‌باکس داخل یک کارت یا Surface است که خودش سایه یا حاشیه دارد و سایهٔ پیش‌فرض روی هم تلنبار می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
با توضیح زیرِ گزینه
برای گزینه‌ای که به توضیح بیشتری نیاز دارد، یک متن کوچک زیرش با تورفتگی هم‌تراز با متن Label بگذارید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
گروه چندانتخابی (CheckboxGroup)
چند Checkbox که هر کدام یک value دارند را داخل CheckboxGroup بگذارید تا آرایهٔ مقادیر انتخاب‌شده با هم هماهنگ شود؛ اینجا یک مقدار از قبل غیرفعال است چون در پلن فعلی موجود نیست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال ذخیره (Loading)
مقدار را بلافاصله عوض نکنید. تا رسیدن پاسخ چک‌باکس قفل و aria-busy روشن باشد؛ اگر درخواست شکست بخورد، UI چیزی را نشان نمی‌دهد که واقعاً ذخیره نشده.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| اینتراکشن (interaction) | واکنش چک‌باکس به فشردن و هاور |
| نامعتبر (Invalid) | برای خطای اعتبارسنجی فرم، invalid بدهید؛ حاشیه قرمز می‌شود و در حالت انتخاب‌شده، رنگ داخل باکس هم به‌جای primary قرمز می‌شود. |
| فقط‌خواندنی (Read-only) | برخلاف disabled، readOnly ظاهر عادی را حفظ می‌کند و در چرخهٔ Tab می‌ماند؛ فقط جلوی تغییر مقدار با کلیک یا کیبورد را می‌گیرد. |
| Variant: default و flat | variant="flat" سایه ندارد و پس‌زمینهٔ خاکستری خنثی می‌گیرد، برای وقتی چک‌باکس داخل یک کارت یا Surface است که خودش سایه یا حاشیه دارد و سایهٔ پیش‌فرض روی هم تلنبار می‌شود. |
| با توضیح زیرِ گزینه | برای گزینه‌ای که به توضیح بیشتری نیاز دارد، یک متن کوچک زیرش با تورفتگی هم‌تراز با متن Label بگذارید. |
| Disabled | گزینه‌ای که به‌خاطر پلن یا شرط دیگری فعلاً قابل تغییر نیست |
| گروه چندانتخابی (CheckboxGroup) | چند Checkbox که هر کدام یک value دارند را داخل CheckboxGroup بگذارید تا آرایهٔ مقادیر انتخاب‌شده با هم هماهنگ شود؛ اینجا یک مقدار از قبل غیرفعال است چون در پلن فعلی موجود نیست. |
| در حال ذخیره (Loading) | تنظیمی که با هر کلیک به سرور می‌رود |
دستورالعمل استفاده
چک‌باکس همیشه با یک Label
انجام بده
با id روی Checkbox و htmlFor یکسان روی Label، هم صفحه‌خوان متن را می‌شنود و هم کلیک روی متن باکس را تیک می‌زند.
انجام نده
چک‌باکس بدون برچسب کنارش، کاربر و صفحه‌خوان را نسبت به معنی گزینه بی‌اطلاع می‌گذارد و ناحیهٔ کلیک هم فقط به همان مربع کوچک محدود می‌ماند.
حالت نامشخص برای انتخاب جزئی
انجام بده
وقتی بعضی از زیرگزینه‌ها انتخاب شده‌اند نه همه، چک‌باکس والد را با checked="indeterminate" نشان بدهید تا وضعیت واقعی گفته شود.
انجام نده
نمایش چک‌باکس والد به‌صورت کاملاً خالی وقتی یکی از زیرگزینه‌ها انتخاب شده، به کاربر می‌گوید هیچ‌کدام انتخاب نشده؛ اطلاعات غلط می‌دهد.
غیرفعال کردن با توضیح دلیل
فقط برای پلن سازمانی فعال است.
انجام بده
اگر گزینه‌ای به‌خاطر شرایط دیگری غیرفعال است، همان دلیل را در متن Label یا نزدیک آن بیاورید تا disabled بی‌توضیح نماند.
انجام نده
چک‌باکس غیرفعال بدون هیچ توضیحی، کاربر را با این سوال تنها می‌گذارد که چرا نمی‌تواند این گزینه را انتخاب کند.
disabled یا readOnly، نه اینکه چک‌باکس ناپدید شود
انجام بده
برای شرطی که کاربر نباید تغییرش دهد ولی باید مقدارش را ببیند (مثلاً یک تعهد اجباری در فرم تأییدشده)، readOnly مقدار را ثابت نگه می‌دارد و همچنان با Tab قابل‌دسترسی است.
✓ سیاست حریم خصوصی تأیید شده
انجام نده
پنهان‌کردن چک‌باکسِ همیشه-تیک‌خورده و نمایش فقط متن ساده، وضعیت را از فرم واقعی جدا می‌کند و اگر کاربر انتظار یک فیلد فرم را داشته باشد گیج‌کننده است.