چک‌باکس (Checkbox)

کامپوننت چک‌باکس برای انتخاب یک یا چند گزینه از مجموعه‌ای از انتخاب‌ها استفاده می‌شود.

نصب (Installation)

1npx @quark-lab/rad-ui add checkbox

نمونه‌ها (Examples)

استفاده پایه (Basic Usage)

ساده‌ترین حالت استفاده از چک‌باکس همراه با برچسب.

پذیرفتن قوانین و مقررات

مشاهده کد

1import { Checkbox } from "@/components/ui/checkbox";
2import { Label } from "@/components/ui/label";
3
4export default function BasicExample() {
5  return (
6    <div className="flex items-center space-x-2 space-x-reverse">
7      <Checkbox id="basic" />
8      <Label htmlFor="basic" className="cursor-pointer">
9        پذیرفتن قوانین و مقررات
10      </Label>
11    </div>
12  );
13}
14

با برچسب (With Label)

استفاده از چک‌باکس در کنار Label برای توضیحات بیشتر.

قوانین و مقررات را می‌پذیرم

از ارسال ایمیل‌های تبلیغاتی مطلع باشم

مشاهده کد

1import { Checkbox } from "@/components/ui/checkbox";
2import { Label } from "@/components/ui/label";
3
4export default function WithLabelExample() {
5  return (
6    <div className="space-y-4">
7      <div className="flex items-center space-x-2 space-x-reverse">
8        <Checkbox id="terms1" />
9        <Label htmlFor="terms1" className="cursor-pointer">
10          قوانین و مقررات را می‌پذیرم
11        </Label>
12      </div>
13      <div className="flex items-center space-x-2 space-x-reverse">
14        <Checkbox id="marketing" />
15        <Label htmlFor="marketing" className="cursor-pointer">
16          از ارسال ایمیل‌های تبلیغاتی مطلع باشم
17        </Label>
18      </div>
19    </div>
20  );
21}
22

کنترل شده (Controlled)

مدیریت وضعیت چک‌باکس با استفاده از React State.

این چک‌باکس کنترل‌شده است

وضعیت: انتخاب نشده

مشاهده کد

1import { useState } from "react";
2import { Checkbox } from "@/components/ui/checkbox";
3import { Label } from "@/components/ui/label";
4
5export default function ControlledExample() {
6  const [checked, setChecked] = useState<boolean>(false);
7
8  return (
9    <div className="space-y-4">
10      <div className="flex items-center space-x-2 space-x-reverse">
11        <Checkbox
12          id="controlled"
13          checked={checked}
14          onCheckedChange={(c) => setChecked(c as boolean)}
15        />
16        <Label htmlFor="controlled" className="cursor-pointer">
17          این چک‌باکس کنترل‌شده است
18        </Label>
19      </div>
20      <p className="text-sm text-muted-foreground">
21        وضعیت: {checked ? "انتخاب شده" : "انتخاب نشده"}
22      </p>
23    </div>
24  );
25}
26

حالت غیرفعال (Disabled)

چک‌باکس‌هایی که کاربر نمی‌تواند با آن‌ها تعامل داشته باشد.

چک‌باکس غیرفعال (انتخاب نشده)

چک‌باکس غیرفعال (انتخاب شده)

مشاهده کد

1import { Checkbox } from "@/components/ui/checkbox";
2import { Label } from "@/components/ui/label";
3
4export default function DisabledExample() {
5  return (
6    <div className="space-y-4">
7      <div className="flex items-center space-x-2 space-x-reverse">
8        <Checkbox id="disabled1" disabled />
9        <Label htmlFor="disabled1" className="cursor-not-allowed opacity-50">
10          چک‌باکس غیرفعال (انتخاب نشده)
11        </Label>
12      </div>
13      <div className="flex items-center space-x-2 space-x-reverse">
14        <Checkbox id="disabled2" disabled checked />
15        <Label htmlFor="disabled2" className="cursor-not-allowed opacity-50">
16          چک‌باکس غیرفعال (انتخاب شده)
17        </Label>
18      </div>
19    </div>
20  );
21}
22

مثال فرم (Form Example)

استفاده از چک‌باکس‌ها در یک فرم تنظیمات واقعی.

تنظیمات اعلان‌ها

اعلان‌های ایمیل

دریافت اعلان‌ها از طریق ایمیل

اعلان‌های پیامکی

دریافت اعلان‌ها از طریق پیامک

اعلان‌های فشاری

دریافت اعلان‌های فشاری در مرورگر

تنظیمات فعلی:

ایمیل: فعال

پیامک: غیرفعال

اعلان فشاری: فعال

مشاهده کد

1import { useState } from "react";
2import { Checkbox } from "@/components/ui/checkbox";
3import { Label } from "@/components/ui/label";
4
5export default function FormExample() {
6  const [notifications, setNotifications] = useState({
7    email: true,
8    sms: false,
9    push: true,
10  });
11
12  return (
13    <div className="space-y-6">
14      <div>
15        <h3 className="text-lg font-semibold mb-4">تنظیمات اعلان‌ها</h3>
16        <div className="space-y-4">
17          <div className="flex items-center space-x-2 space-x-reverse">
18            <Checkbox
19              id="email-notif"
20              checked={notifications.email}
21              onCheckedChange={(checked) =>
22                setNotifications((prev) => ({
23                  ...prev,
24                  email: checked as boolean,
25                }))
26              }
27            />
28            <div className="flex flex-col">
29              <Label htmlFor="email-notif" className="cursor-pointer">
30                اعلان‌های ایمیل
31              </Label>
32              <p className="text-sm text-muted-foreground">
33                دریافت اعلان‌ها از طریق ایمیل
34              </p>
35            </div>
36          </div>
37          <div className="flex items-center space-x-2 space-x-reverse">
38            <Checkbox
39              id="sms-notif"
40              checked={notifications.sms}
41              onCheckedChange={(checked) =>
42                setNotifications((prev) => ({
43                  ...prev,
44                  sms: checked as boolean,
45                }))
46              }
47            />
48            <div className="flex flex-col">
49              <Label htmlFor="sms-notif" className="cursor-pointer">
50                اعلان‌های پیامکی
51              </Label>
52              <p className="text-sm text-muted-foreground">
53                دریافت اعلان‌ها از طریق پیامک
54              </p>
55            </div>
56          </div>
57          <div className="flex items-center space-x-2 space-x-reverse">
58            <Checkbox
59              id="push-notif"
60              checked={notifications.push}
61              onCheckedChange={(checked) =>
62                setNotifications((prev) => ({
63                  ...prev,
64                  push: checked as boolean,
65                }))
66              }
67            />
68            <div className="flex flex-col">
69              <Label htmlFor="push-notif" className="cursor-pointer">
70                اعلان‌های فشاری
71              </Label>
72              <p className="text-sm text-muted-foreground">
73                دریافت اعلان‌های فشاری در مرورگر
74              </p>
75            </div>
76          </div>
77        </div>
78      </div>
79      <div className="pt-4 border-t">
80        <h4 className="text-sm font-semibold mb-2">تنظیمات فعلی:</h4>
81        <div className="text-sm text-muted-foreground space-y-1">
82          <p>ایمیل: {notifications.email ? "فعال" : "غیرفعال"}</p>
83          <p>پیامک: {notifications.sms ? "فعال" : "غیرفعال"}</p>
84          <p>اعلان فشاری: {notifications.push ? "فعال" : "غیرفعال"}</p>
85        </div>
86      </div>
87    </div>
88  );
89}
90

پذیرش قوانین (Terms Acceptance)

استفاده از چک‌باکس برای تایید قوانین قبل از ادامه.

قوانین و مقررات را مطالعه کرده و می‌پذیرم

با ثبت‌نام، شما شرایط استفاده و سیاست حفظ حریم خصوصی ما را می‌پذیرید

مشاهده کد

1import { useState } from "react";
2import { Checkbox } from "@/components/ui/checkbox";
3import { Label } from "@/components/ui/label";
4import { Button } from "@/components/ui/button";
5
6export default function TermsExample() {
7  const [termsAccepted, setTermsAccepted] = useState(false);
8
9  return (
10    <div className="space-y-4">
11      <div className="flex items-start space-x-2 space-x-reverse">
12        <Checkbox
13          id="terms"
14          checked={termsAccepted}
15          onCheckedChange={(checked) => setTermsAccepted(checked as boolean)}
16          className="mt-1"
17        />
18        <div className="flex flex-col">
19          <Label htmlFor="terms" className="cursor-pointer">
20            قوانین و مقررات را مطالعه کرده و می‌پذیرم
21          </Label>
22          <p className="text-sm text-muted-foreground mt-1">
23            با ثبت‌نام، شما{" "}
24            <a href="#" className="text-primary hover:underline">
25              شرایط استفاده
26            </a>{" "}
27            و{" "}
28            <a href="#" className="text-primary hover:underline">
29              سیاست حفظ حریم خصوصی
30            </a>{" "}
31            ما را می‌پذیرید
32          </p>
33        </div>
34      </div>
35      <Button disabled={!termsAccepted}>ادامه ثبت‌نام</Button>
36    </div>
37  );
38}
39

مرجع API (API Reference)

Checkbox

پراپ‌های کامپوننت چک‌باکس.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`checked`	`boolean \| "indeterminate"`	`undefined`	وضعیت انتخاب شده (کنترل‌شده)
`defaultChecked`	`boolean`	`false`	وضعیت پیش‌فرض (غیرکنترل‌شده)
`onCheckedChange`	`(checked: boolean \| "indeterminate") => void`	`-`	تابع فراخوانی هنگام تغییر وضعیت
`disabled`	`boolean`	`false`	غیرفعال کردن چک‌باکس
`required`	`boolean`	`false`	الزامی بودن در فرم
`name`	`string`	`-`	نام فیلد برای ارسال فرم
`value`	`string`	`"on"`	مقدار ارسالی در فرم
`id`	`string`	`-`	شناسه یکتا برای ارتباط با Label

دسترسی‌پذیری (Accessibility)

کیبورد (Keyboard)

Space - تغییر وضعیت چک‌باکس
Tab - حرکت به چک‌باکس بعدی

برچسب‌ها (Labels)

همیشه از کامپوننت Label با ویژگی htmlFor استفاده کنید تا چک‌باکس را با برچسب مرتبط کنید

وضعیت (State)

وضعیت چک‌باکس از طریق aria-checked به صورت خودکار اعلام می‌شود

بهترین شیوه‌ها (Best Practices)

برچسب واضح (Clear Labels)

همیشه از Label همراه با Checkbox استفاده کنید و برچسب‌های واضح و مختصر بنویسید

انتخاب‌های مستقل (Independent Choices)

از Checkbox برای انتخاب‌های مستقل استفاده کنید. برای انتخاب‌های انحصاری از Radio Button استفاده کنید

تفاوت با Switch

از Checkbox برای انتخاب‌های چندگانه که نیاز به تایید دارند و از Switch برای تنظیمات فوری (روشن/خاموش) استفاده کنید

گروه‌بندی (Grouping)

چک‌باکس‌های مرتبط را در گروه‌های منطقی دسته‌بندی کنید و از تعداد زیاد چک‌باکس در یک گروه خودداری کنید

نحوه استفاده (Usage)

1import { useState } from "react";
2import { Checkbox } from "@/components/ui/checkbox";
3import { Label } from "@/components/ui/label"
4
5export default function UsageExample() {
6  const [checked, setChecked] = useState(false);
7
8  return (
9    <div className="flex flex-col gap-6">
10      {/* Basic */}
11      <div className="flex items-center space-x-2 space-x-reverse">
12        <Checkbox id="basic-usage" />
13        <Label htmlFor="basic-usage">پذیرفتن قوانین</Label>
14      </div>
15
16      {/* Controlled */}
17      <div className="flex items-center space-x-2 space-x-reverse">
18        <Checkbox
19          id="controlled-usage"
20          checked={checked}
21          onCheckedChange={(c) => setChecked(c as boolean)}
22        />
23        <Label htmlFor="controlled-usage">چک‌باکس کنترل‌شده</Label>
24      </div>
25
26      {/* Disabled */}
27      <div className="flex gap-4">
28        <Checkbox disabled />
29        <Checkbox disabled checked />
30      </div>
31
32      {/* With description */}
33      <div className="flex items-center space-x-2 space-x-reverse">
34        <Checkbox id="desc-usage" />
35        <div className="flex flex-col">
36          <Label htmlFor="desc-usage">اعلان‌ها را فعال کن</Label>
37          <p className="text-sm text-muted-foreground">
38            دریافت اخبار و بروزرسانی‌ها
39          </p>
40        </div>
41      </div>
42    </div>
43  );
44}
45

مثال‌های پیشرفته (Advanced Examples)

انتخاب چندگانه (Multiple Selection)

پیاده‌سازی الگوی انتخاب همه / هیچکدام با حالت indeterminate.

انتخاب همه

گزینه ۱

گزینه ۲

گزینه ۳

0 گزینه انتخاب شده

مشاهده کد

1import { useState } from "react";
2import { Checkbox } from "@/components/ui/checkbox";
3import { Label } from "@/components/ui/label";
4
5export default function MultipleExample() {
6  const [items, setItems] = useState([
7    { id: "item1", label: "گزینه ۱", checked: false },
8    { id: "item2", label: "گزینه ۲", checked: false },
9    { id: "item3", label: "گزینه ۳", checked: false },
10  ]);
11
12  const allChecked = items.length > 0 && items.every((item) => item.checked);
13  const isIndeterminate =
14    items.some((item) => item.checked) && !allChecked;
15
16  const toggleAll = (checked: boolean) => {
17    setItems(items.map((item) => ({ ...item, checked })));
18  };
19
20  const toggleItem = (id: string) => {
21    setItems(
22      items.map((item) =>
23        item.id === id ? { ...item, checked: !item.checked } : item
24      )
25    );
26  };
27
28  return (
29    <div className="space-y-4">
30      <div className="flex items-center space-x-2 space-x-reverse border-b border-border pb-2">
31        <Checkbox
32          id="select-all"
33          checked={allChecked ? true : isIndeterminate ? "indeterminate" : false}
34          onCheckedChange={(checked) => toggleAll(checked as boolean)}
35        />
36        <Label htmlFor="select-all" className="cursor-pointer font-bold">
37          انتخاب همه
38        </Label>
39      </div>
40      <div className="flex flex-col gap-3 me-6">
41        {items.map((item) => (
42          <div key={item.id} className="flex items-center space-x-2 space-x-reverse">
43            <Checkbox
44              id={item.id}
45              checked={item.checked}
46              onCheckedChange={() => toggleItem(item.id)}
47            />
48            <Label htmlFor={item.id} className="cursor-pointer">
49              {item.label}
50            </Label>
51          </div>
52        ))}
53      </div>
54      <div className="text-sm text-muted-foreground pt-2">
55        {items.filter(i => i.checked).length} گزینه انتخاب شده
56      </div>
57    </div>
58  );
59}
60