سوئیچ (Switch)

کنترلی که به کاربر امکان می‌دهد بین حالت فعال و غیرفعال جابه‌جا شود.

نصب (Installation)

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

نمونه‌ها (Examples)

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

استفاده ساده از سوئیچ.

مشاهده کد
1import { Switch } from "@/components/ui/switch";
2
3export default function BasicExample() {
4  return <Switch />;
5}
6

با برچسب (With Label)

استفاده از سوئیچ همراه با برچسب.

مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function WithLabelExample() {
5  return (
6    <div className="flex items-center space-x-2 space-x-reverse">
7      <Switch id="airplane-mode" />
8      <Label htmlFor="airplane-mode">حالت هواپیما</Label>
9    </div>
10  );
11}
12

پیش‌فرض فعال (Default Checked)

تنظیم وضعیت پیش‌فرض سوئیچ به حالت فعال.

مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function DefaultCheckedExample() {
5  return (
6    <div className="flex items-center space-x-2 space-x-reverse">
7      <Switch id="notifications" defaultChecked />
8      <Label htmlFor="notifications">اعلان‌ها</Label>
9    </div>
10  );
11}
12

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

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

مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function DisabledExample() {
5  return (
6    <div className="flex flex-col gap-4">
7      <div className="flex items-center space-x-2 space-x-reverse">
8        <Switch id="disabled-off" disabled />
9        <Label htmlFor="disabled-off" className="opacity-50">
10          غیرفعال شده
11        </Label>
12      </div>
13      <div className="flex items-center space-x-2 space-x-reverse">
14        <Switch id="disabled-on" disabled defaultChecked />
15        <Label htmlFor="disabled-on" className="opacity-50">
16          همیشه فعال
17        </Label>
18      </div>
19    </div>
20  );
21}
22

کنترل شده (Controlled)

مدیریت وضعیت سوئیچ از طریق state.

وضعیت فعلی: غیرفعال

مشاهده کد
1import { useState } from "react";
2import { Switch } from "@/components/ui/switch";
3import { Label } from "@/components/ui/label";
4
5export default function ControlledExample() {
6  const [isEnabled, setIsEnabled] = useState(false);
7
8  return (
9    <div className="space-y-4">
10      <div className="flex items-center space-x-2 space-x-reverse">
11        <Switch
12          id="controlled"
13          checked={isEnabled}
14          onCheckedChange={setIsEnabled}
15        />
16        <Label htmlFor="controlled">فعال کردن ویژگی</Label>
17      </div>
18      <p className="text-sm text-muted-foreground">
19        وضعیت فعلی: {isEnabled ? "فعال" : "غیرفعال"}
20      </p>
21    </div>
22  );
23}
24

با توضیحات (With Description)

افزودن توضیحات بیشتر برای سوئیچ.

دریافت ایمیل‌ها درباره محصولات جدید و پیشنهادات ویژه

دریافت اعلان درباره فعالیت‌های مشکوک در حساب کاربری

مشاهده کد
1import { useState } from "react";
2import { Switch } from "@/components/ui/switch";
3import { Label } from "@/components/ui/label";
4
5export default function WithDescriptionExample() {
6  const [marketing, setMarketing] = useState(true);
7  const [security, setSecurity] = useState(false);
8
9  return (
10    <div className="space-y-6">
11      <div className="flex items-center justify-between">
12        <div className="space-y-0.5">
13          <Label htmlFor="marketing">ایمیل‌های بازاریابی</Label>
14          <p className="text-sm text-muted-foreground">
15            دریافت ایمیل‌ها درباره محصولات جدید و پیشنهادات ویژه
16          </p>
17        </div>
18        <Switch
19          id="marketing"
20          checked={marketing}
21          onCheckedChange={setMarketing}
22        />
23      </div>
24
25      <div className="flex items-center justify-between">
26        <div className="space-y-0.5">
27          <Label htmlFor="security">اعلان‌های امنیتی</Label>
28          <p className="text-sm text-muted-foreground">
29            دریافت اعلان درباره فعالیت‌های مشکوک در حساب کاربری
30          </p>
31        </div>
32        <Switch
33          id="security"
34          checked={security}
35          onCheckedChange={setSecurity}
36        />
37      </div>
38    </div>
39  );
40}
41

یکپارچگی با فرم (Form Integration)

استفاده از سوئیچ در یک فرم استاندارد.

غیرفعال کردن تمام اتصالات بی‌سیم

مشاهده کد
1import { useState } from "react";
2import { Switch } from "@/components/ui/switch";
3import { Label } from "@/components/ui/label";
4import { Button } from "@/components/ui/button";
5
6export default function FormExample() {
7  const [airplane, setAirplane] = useState(false);
8
9  return (
10    <form
11      className="space-y-6"
12      onSubmit={(e) => {
13        e.preventDefault();
14        const formData = new FormData(e.currentTarget);
15        console.log("Form data:", Object.fromEntries(formData));
16      }}
17    >
18      <div className="flex items-center justify-between">
19        <div className="space-y-0.5">
20          <Label htmlFor="form-airplane">حالت هواپیما</Label>
21          <p className="text-sm text-muted-foreground">
22            غیرفعال کردن تمام اتصالات بی‌سیم
23          </p>
24        </div>
25        <Switch
26          id="form-airplane"
27          name="airplaneMode"
28          checked={airplane}
29          onCheckedChange={setAirplane}
30        />
31      </div>
32
33      <div className="flex gap-4">
34        <Button type="submit">ذخیره تنظیمات</Button>
35        <Button
36          type="button"
37          variant="outline"
38          onClick={() => {
39            setAirplane(false);
40            console.log("Settings reset");
41          }}
42        >
43          بازنشانی
44        </Button>
45      </div>
46    </form>
47  );
48}
49

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

پنل تنظیمات (Settings Panel)

گروهی از سوئیچ‌ها برای تنظیمات مختلف.

اعلان‌ها

نمایش اعلان هنگام دریافت پیام جدید

نمایش اعلان‌ها روی دسکتاپ

پخش صدا هنگام دریافت اعلان

حریم خصوصی

نمایش وضعیت حضور شما به دیگران

به اشتراک گذاشتن موقعیت مکانی شما

مشاهده کد
1import { Switch } from "@/components/ui/switch";
2import { Label } from "@/components/ui/label";
3
4export default function SettingsExample() {
5  return (
6    <div className="space-y-6">
7      <div>
8        <h3 className="text-lg font-semibold mb-4">اعلان‌ها</h3>
9        <div className="space-y-4">
10          <div className="flex items-center justify-between">
11            <div className="space-y-0.5">
12              <Label>پیام‌های جدید</Label>
13              <p className="text-sm text-muted-foreground">
14                نمایش اعلان هنگام دریافت پیام جدید
15              </p>
16            </div>
17            <Switch defaultChecked />
18          </div>
19
20          <div className="flex items-center justify-between">
21            <div className="space-y-0.5">
22              <Label>اعلان‌های دسکتاپ</Label>
23              <p className="text-sm text-muted-foreground">
24                نمایش اعلان‌ها روی دسکتاپ
25              </p>
26            </div>
27            <Switch />
28          </div>
29
30          <div className="flex items-center justify-between">
31            <div className="space-y-0.5">
32              <Label>صدای اعلان</Label>
33              <p className="text-sm text-muted-foreground">
34                پخش صدا هنگام دریافت اعلان
35              </p>
36            </div>
37            <Switch defaultChecked />
38          </div>
39        </div>
40      </div>
41
42      <div className="border-t border-border pt-6">
43        <h3 className="text-lg font-semibold mb-4">حریم خصوصی</h3>
44        <div className="space-y-4">
45          <div className="flex items-center justify-between">
46            <div className="space-y-0.5">
47              <Label>نمایش وضعیت آنلاین</Label>
48              <p className="text-sm text-muted-foreground">
49                نمایش وضعیت حضور شما به دیگران
50              </p>
51            </div>
52            <Switch defaultChecked />
53          </div>
54
55          <div className="flex items-center justify-between">
56            <div className="space-y-0.5">
57              <Label>اشتراک‌گذاری موقعیت</Label>
58              <p className="text-sm text-muted-foreground">
59                به اشتراک گذاشتن موقعیت مکانی شما
60              </p>
61            </div>
62            <Switch />
63          </div>
64        </div>
65      </div>
66    </div>
67  );
68}
69

تنظیمات با ذخیره خودکار (Auto-save Settings)

ذخیره خودکار تنظیمات پس از تغییر.

این یک مثال کد است و پیش‌نمایش ندارد.
مشاهده کد
1const [settings, setSettings] = useState({
2  notifications: true,
3  darkMode: false,
4  analytics: true
5});
6
7// Auto-save on change
8const updateSetting = (key, value) => {
9  setSettings(prev => {
10    const newSettings = { ...prev, [key]: value };
11    // Save to API or localStorage
12    localStorage.setItem('settings', JSON.stringify(newSettings));
13    return newSettings;
14  });
15};
16
17<div className="space-y-4">
18  <div className="flex items-center justify-between">
19    <Label>Enable Notifications</Label>
20    <Switch
21      checked={settings.notifications}
22      onCheckedChange={(checked) =>
23        updateSetting('notifications', checked)
24      }
25    />
26  </div>
27  {/* ... other settings */}
28</div>

مرجع API (API Reference)

Switch

پراپ‌های کامپوننت Switch.

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
checkedbooleanundefinedوضعیت کنترل شده
defaultCheckedbooleanfalseوضعیت پیش‌فرض (غیرکنترل شده)
onCheckedChange(checked: boolean) => voidundefinedتابع فراخوانی هنگام تغییر وضعیت
disabledbooleanfalseغیرفعال کردن سوئیچ
requiredbooleanfalseاجباری بودن در فرم
namestringundefinedنام فیلد برای ارسال فرم
valuestring"on"مقدار ارسالی در فرم
classNamestringundefinedکلاس‌های CSS سفارشی

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

کیبورد (Keyboard)

  • Space - تغییر وضعیت سوئیچ
  • Enter - تغییر وضعیت سوئیچ
  • Tab - حرکت به سوئیچ بعدی

ARIA نقش (ARIA Role)

کامپوننت از نقش switch استفاده می‌کند که برای خوانندگان صفحه مناسب است

برچسب‌ها (Labels)

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

وضعیت (State)

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

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

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

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

تاثیر فوری (Immediate Effect)

سوئیچ باید تنظیمات را بلافاصله اعمال کند. اگر نیاز به تایید دارید، از Checkbox استفاده کنید.

توضیحات کمکی (Helper Text)

برای تنظیمات پیچیده، متن توضیحی اضافه کنید تا کاربر بداند چه اتفاقی می‌افتد

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

سوئیچ‌های مرتبط را در بخش‌های منطقی دسته‌بندی کنید (مثل اعلان‌ها، حریم خصوصی)

تفاوت با Checkbox

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