دکمه دوحالته (Toggle)

کامپوننت دکمه دوحالته که می‌تواند روشن یا خاموش باشد، با پشتیبانی کامل از RTL و حالت تاریک.

نصب (Installation)

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

نمونه‌ها (Examples)

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

استفاده ساده از دکمه دوحالته.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2import { Bold } from "lucide-react";
3
4export default function BasicExample() {
5  return (
6    <Toggle aria-label="Toggle bold">
7      <Bold className="h-4 w-4" />
8    </Toggle>
9  );
10}
11

انواع (Variants)

انواع مختلف ظاهری دکمه دوحالته.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2import { Bold, Italic, Underline } from "lucide-react";
3
4export default function VariantsExample() {
5  return (
6    <div className="flex flex-col gap-4">
7      <div className="flex flex-wrap gap-4">
8        <Toggle variant="default" aria-label="Toggle italic">
9          <Italic className="h-4 w-4" />
10        </Toggle>
11        <Toggle variant="default" aria-label="Toggle bold">
12          <Bold className="h-4 w-4" />
13        </Toggle>
14        <Toggle variant="default" aria-label="Toggle underline">
15          <Underline className="h-4 w-4" />
16        </Toggle>
17      </div>
18      <div className="flex flex-wrap gap-4">
19        <Toggle variant="outline" aria-label="Toggle italic">
20          <Italic className="h-4 w-4" />
21        </Toggle>
22        <Toggle variant="outline" aria-label="Toggle bold">
23          <Bold className="h-4 w-4" />
24        </Toggle>
25        <Toggle variant="outline" aria-label="Toggle underline">
26          <Underline className="h-4 w-4" />
27        </Toggle>
28      </div>
29    </div>
30  );
31}
32

اندازه‌ها (Sizes)

اندازه‌های مختلف دکمه دوحالته.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2import { Italic } from "lucide-react";
3
4export default function SizesExample() {
5  return (
6    <div className="flex flex-wrap items-center gap-4">
7      <Toggle size="sm" aria-label="Toggle small">
8        <Italic className="h-3 w-3" />
9      </Toggle>
10      <Toggle size="md" aria-label="Toggle medium">
11        <Italic className="h-4 w-4" />
12      </Toggle>
13      <Toggle size="lg" aria-label="Toggle large">
14        <Italic className="h-5 w-5" />
15      </Toggle>
16    </div>
17  );
18}
19

با متن (With Text)

دکمه دوحالته همراه با آیکون و متن.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2import { Bold, Italic, Underline } from "lucide-react";
3
4export default function WithTextExample() {
5  return (
6    <div className="flex flex-wrap gap-4">
7      <Toggle aria-label="Toggle italic">
8        <Italic className="ms-2 h-4 w-4" />
9        کج
10      </Toggle>
11      <Toggle aria-label="Toggle bold">
12        <Bold className="ms-2 h-4 w-4" />
13        پررنگ
14      </Toggle>
15      <Toggle aria-label="Toggle underline">
16        <Underline className="ms-2 h-4 w-4" />
17        زیرخط
18      </Toggle>
19    </div>
20  );
21}
22

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

دکمه دوحالته غیرفعال.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2import { Italic } from "lucide-react";
3
4export default function DisabledExample() {
5  return (
6    <Toggle disabled aria-label="Toggle italic">
7      <Italic className="h-4 w-4" />
8    </Toggle>
9  );
10}
11

مثال تعاملی (Interactive Example)

نمایش تغییر وضعیت دکمه‌ها در کنسول.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2import { Bold, Italic, Underline } from "lucide-react";
3
4export default function InteractiveExample() {
5  return (
6    <div className="flex flex-wrap gap-4">
7      <Toggle
8        variant="outline"
9        onPressedChange={(pressed) =>
10          console.log("Italic:", pressed ? "فعال" : "غیرفعال")
11        }
12        aria-label="Toggle italic"
13      >
14        <Italic className="ms-2 h-4 w-4" />
15        کج
16      </Toggle>
17      <Toggle
18        variant="outline"
19        onPressedChange={(pressed) =>
20          console.log("Bold:", pressed ? "فعال" : "غیرفعال")
21        }
22        aria-label="Toggle bold"
23      >
24        <Bold className="ms-2 h-4 w-4" />
25        پررنگ
26      </Toggle>
27      <Toggle
28        variant="outline"
29        onPressedChange={(pressed) =>
30          console.log("Underline:", pressed ? "فعال" : "غیرفعال")
31        }
32        aria-label="Toggle underline"
33      >
34        <Underline className="ms-2 h-4 w-4" />
35        زیرخط
36      </Toggle>
37    </div>
38  );
39}
40

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

استایل سفارشی (Custom Styling)

استفاده از کلاس‌های سفارشی برای تغییر ظاهر دکمه.

مشاهده کد

1import { Toggle } from "@/components/ui/toggle";
2
3export default function CustomStylingExample() {
4  return (
5    <Toggle className="data-[state=on]:bg-green-500 data-[state=on]:text-white data-[state=on]:hover:bg-green-600 data-[state=on]:hover:text-white">
6      سفارشی
7    </Toggle>
8  );
9}
10

نوار ابزار قالب‌بندی (Formatting Toolbar)

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

مشاهده کد

1import { useState } from "react";
2import { Toggle } from "@/components/ui/toggle";
3import { Bold, Italic, Underline } from "lucide-react";
4
5export default function FormattingToolbarExample() {
6  const [formatting, setFormatting] = useState({
7    bold: false,
8    italic: false,
9    underline: false,
10  });
11
12  return (
13    <div className="flex gap-1 p-1 border rounded-lg w-fit">
14      <Toggle
15        pressed={formatting.bold}
16        onPressedChange={(pressed) =>
17          setFormatting({ ...formatting, bold: pressed })
18        }
19        variant="ghost"
20        size="sm"
21        aria-label="Toggle bold"
22      >
23        <Bold className="h-4 w-4" />
24      </Toggle>
25      <Toggle
26        pressed={formatting.italic}
27        onPressedChange={(pressed) =>
28          setFormatting({ ...formatting, italic: pressed })
29        }
30        variant="ghost"
31        size="sm"
32        aria-label="Toggle italic"
33      >
34        <Italic className="h-4 w-4" />
35      </Toggle>
36      <Toggle
37        pressed={formatting.underline}
38        onPressedChange={(pressed) =>
39          setFormatting({ ...formatting, underline: pressed })
40        }
41        variant="ghost"
42        size="sm"
43        aria-label="Toggle underline"
44      >
45        <Underline className="h-4 w-4" />
46      </Toggle>
47    </div>
48  );
49}
50

مرجع API (API Reference)

Toggle

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

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`variant`	`"default" \| "outline"`	`"default"`	نوع ظاهری دکمه
`size`	`"sm" \| "md" \| "lg"`	`"md"`	اندازه دکمه
`pressed`	`boolean`	`undefined`	وضعیت فعال/غیرفعال (کنترل شده)
`defaultPressed`	`boolean`	`false`	وضعیت اولیه (غیرکنترل شده)
`onPressedChange`	`(pressed: boolean) => void`	`undefined`	تابع فراخوانی هنگام تغییر وضعیت
`disabled`	`boolean`	`false`	غیرفعال کردن دکمه
`aria-label`	`string`	`-`	برچسب دسترسی‌پذیری (ضروری)
`className`	`string`	`undefined`	کلاس‌های CSS سفارشی

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

کیبورد (Keyboard)

Space - تغییر وضعیت دکمه
Enter - تغییر وضعیت دکمه
Tab - حرکت به دکمه بعدی

ARIA برچسب‌های (ARIA Labels)

همیشه از aria-label استفاده کنید تا کاربران خوانندگان صفحه بتوانند هدف دکمه را درک کنند

وضعیت (State)

دکمه به‌طور خودکار ویژگی data-state را با مقادیر "on" یا "off" تنظیم می‌کند

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

انتخاب نوع مناسب (Variant Selection)

Default: برای استفاده عمومی در نوارهای ابزار
Outline: برای تمایز بیشتر در رابط کاربری

آیکون‌ها در RTL (Icons in RTL)

از ms-2 برای آیکون در سمت راست متن استفاده کنید تا در RTL صحیح نمایش داده شود.

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

همیشه aria-label را برای دکمه‌های Toggle تنظیم کنید، به‌ویژه زمانی که فقط آیکون دارند.

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

برای دکمه‌های مرتبط مانند تراز متن یا قالب‌بندی، از گروه‌بندی بصری با فاصله‌گذاری مناسب استفاده کنید.