چکباکس (Checkbox)
کنترل فرم برای انتخاب چند گزینهای
معرفی
کامپوننت Checkbox برای انتخاب یک یا چند گزینه استفاده میشود.
چه زمانی استفاده نکنیم:
- برای انتخاب منحصربهفرد (یکی از چند گزینه) — از
RadioGroupاستفاده کنید - برای هر فیلد روشن/خاموش، با اثر فوری یا ثبتشده با دکمهٔ «ذخیره» فرم (مانند «ارسال ایمیل») — از
Switchاستفاده کنید - برای «چند گزینه از چند گزینه» در یک فیلد فرم، یا انتخاب از لیست بزرگ — از
MultiSelectاستفاده کنید (هرگز گروهی ازCheckboxها در یکFormRow)
حالت انتخابشده خنثی است
حالت checked اکنون از دستور خنثی (foreground) استفاده میکند: پسزمینهٔ foreground و تیک background
(data-[state=checked]:bg-foreground text-background) — مطابق چکباکس واقعی Supabase. رنگ سبز برند برای اقدامات اصلی
رزرو است؛ حلقهٔ focus برای هماهنگی با سایر کنترلهای فرم همچنان برند میماند.
استفاده
import { Checkbox } from '@partodata/ui'
export default function MyComponent() {
return (
<div className="flex items-center gap-2">
<Checkbox id="terms" />
<label htmlFor="terms">قوانین را میپذیرم</label>
</div>
)
}زمین بازی
با تغییر تنظیمات زیر، چکباکس را به صورت زنده مشاهده کنید.
زمین بازی
تنظیمات
حالت
محتوا
کد این نمونه بهصورت خودکار قابل تولید نیست — برای کد آمادهی copy/paste به بخش «استفاده» در بالای صفحه مراجعه کنید.
با فرم
import { Checkbox } from '@partodata/ui'
import { Label } from '@partodata/ui'
export default function MyComponent() {
return (
<div className="flex items-center gap-2">
<Checkbox id="remember" />
<Label htmlFor="remember">مرا به خاطر بسپار</Label>
</div>
)
}حالت نامشخص (Indeterminate)
import { Checkbox } from '@partodata/ui'
;<Checkbox checked="indeterminate" />مناسب برای checkbox والد در لیستهای چندسطحی که بعضی فرزندان انتخاب شده و بعضی نه.
حالتها و انواع
حالتهای مختلف
<div className="flex flex-col gap-4" dir="rtl">
<div className="flex items-center gap-2">
<Checkbox id="active" />
<label htmlFor="active">فعال</label>
</div>
<div className="flex items-center gap-2">
<Checkbox id="checked" defaultChecked />
<label htmlFor="checked">انتخابشده</label>
</div>
<div className="flex items-center gap-2">
<Checkbox id="disabled-cb" disabled />
<label htmlFor="disabled-cb">غیرفعال</label>
</div>
<div className="flex items-center gap-2">
<Checkbox id="disabled-checked" disabled defaultChecked />
<label htmlFor="disabled-checked">غیرفعال و انتخابشده</label>
</div>
</div>راهنمای استفاده
بکنید
- از Checkbox در فرمها برای پذیرش شرایط، و در فهرستها و جدولها برای انتخاب ردیفها استفاده کنید - همیشه Checkbox را
با
Labelهمراه کنید تا ناحیه کلیک بزرگتر و هدف مشخصتر شود - از حالتindeterminateبرای checkbox والد در لیستهای چندسطحی استفاده کنید
نکنید
- برای هیچ فیلد روشن/خاموشی (مانند روشن/خاموش کردن اعلانها، حتی در فرمی با «ذخیره») از Checkbox استفاده نکنید — از
Switchاستفاده کنید - برای انتخاب منحصربهفرد (یکی از چند گزینه) از Checkbox استفاده نکنید — ازRadioGroupاستفاده کنید - Checkbox را بدون label متنی رها نکنید
Props
دسترسیپذیری
- از
role="checkbox"استفاده میشود aria-checkedوضعیت انتخاب را اعلام میکند (شاملmixedبرای indeterminate)- همیشه با
idوlabel[for]یاLabel[htmlFor]همراه کنید - از صفحهکلید با Space قابل فعالسازی است
تعامل با کیبورد
Space: تغییر وضعیت (تیک/بدون تیک) -Tab: انتقال فوکوس
کامپوننتهای مرتبط
- Switch — برای هر فیلد روشن/خاموش (با اثر فوری یا ثبتشده با فرم)، از Switch استفاده کنید
- RadioGroup — اگر کاربر باید فقط یک گزینه از بین چند گزینه انتخاب کند، از RadioGroup استفاده کنید
- MultiSelect — اگر تعداد گزینهها زیاد است و نیاز به جستجو دارید، از MultiSelect استفاده کنید