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

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

نصب (Installation)

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

نمونه‌ها (Examples)

انتخاب تکی (Single Selection)

گروه دکمه با امکان انتخاب تنها یک گزینه.

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
2import { AlignLeft, AlignCenter, AlignRight } from "lucide-react";
3
4export default function SingleSelectionExample() {
5  return (
6    <ToggleGroup type="single" defaultValue="center">
7      <ToggleGroupItem value="right" aria-label="Align right">
8        <AlignRight className="h-4 w-4" />
9      </ToggleGroupItem>
10      <ToggleGroupItem value="center" aria-label="Align center">
11        <AlignCenter className="h-4 w-4" />
12      </ToggleGroupItem>
13      <ToggleGroupItem value="left" aria-label="Align left">
14        <AlignLeft className="h-4 w-4" />
15      </ToggleGroupItem>
16    </ToggleGroup>
17  );
18}
19

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

گروه دکمه با امکان انتخاب چندین گزینه همزمان.

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
2import { Bold, Italic, Underline } from "lucide-react";
3
4export default function MultipleSelectionExample() {
5  return (
6    <ToggleGroup type="multiple" defaultValue={["bold"]}>
7      <ToggleGroupItem value="bold" aria-label="Toggle bold">
8        <Bold className="h-4 w-4" />
9      </ToggleGroupItem>
10      <ToggleGroupItem value="italic" aria-label="Toggle italic">
11        <Italic className="h-4 w-4" />
12      </ToggleGroupItem>
13      <ToggleGroupItem value="underline" aria-label="Toggle underline">
14        <Underline className="h-4 w-4" />
15      </ToggleGroupItem>
16    </ToggleGroup>
17  );
18}
19

انواع (Variants)

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

Default:

Outline:

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
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 items-center gap-4">
8        <span className="text-sm font-medium w-20">Default:</span>
9        <ToggleGroup type="single" variant="default">
10          <ToggleGroupItem value="bold" aria-label="Bold">
11            <Bold className="h-4 w-4" />
12          </ToggleGroupItem>
13          <ToggleGroupItem value="italic" aria-label="Italic">
14            <Italic className="h-4 w-4" />
15          </ToggleGroupItem>
16          <ToggleGroupItem value="underline" aria-label="Underline">
17            <Underline className="h-4 w-4" />
18          </ToggleGroupItem>
19        </ToggleGroup>
20      </div>
21      <div className="flex items-center gap-4">
22        <span className="text-sm font-medium w-20">Outline:</span>
23        <ToggleGroup type="single" variant="outline">
24          <ToggleGroupItem value="bold" aria-label="Bold">
25            <Bold className="h-4 w-4" />
26          </ToggleGroupItem>
27          <ToggleGroupItem value="italic" aria-label="Italic">
28            <Italic className="h-4 w-4" />
29          </ToggleGroupItem>
30          <ToggleGroupItem value="underline" aria-label="Underline">
31            <Underline className="h-4 w-4" />
32          </ToggleGroupItem>
33        </ToggleGroup>
34      </div>
35    </div>
36  );
37}
38

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

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

Small:

Medium:

Large:

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
2import { LayoutGrid, LayoutList, Rows3 } from "lucide-react";
3
4export default function SizesExample() {
5  return (
6    <div className="flex flex-col gap-4">
7      <div className="flex items-center gap-4">
8        <span className="text-sm font-medium w-20">Small:</span>
9        <ToggleGroup type="single" size="sm" variant="outline">
10          <ToggleGroupItem value="grid" aria-label="Grid view">
11            <LayoutGrid className="h-3 w-3" />
12          </ToggleGroupItem>
13          <ToggleGroupItem value="list" aria-label="List view">
14            <LayoutList className="h-3 w-3" />
15          </ToggleGroupItem>
16          <ToggleGroupItem value="rows" aria-label="Rows view">
17            <Rows3 className="h-3 w-3" />
18          </ToggleGroupItem>
19        </ToggleGroup>
20      </div>
21      <div className="flex items-center gap-4">
22        <span className="text-sm font-medium w-20">Medium:</span>
23        <ToggleGroup type="single" size="md" variant="outline">
24          <ToggleGroupItem value="grid" aria-label="Grid view">
25            <LayoutGrid className="h-4 w-4" />
26          </ToggleGroupItem>
27          <ToggleGroupItem value="list" aria-label="List view">
28            <LayoutList className="h-4 w-4" />
29          </ToggleGroupItem>
30          <ToggleGroupItem value="rows" aria-label="Rows view">
31            <Rows3 className="h-4 w-4" />
32          </ToggleGroupItem>
33        </ToggleGroup>
34      </div>
35      <div className="flex items-center gap-4">
36        <span className="text-sm font-medium w-20">Large:</span>
37        <ToggleGroup type="single" size="lg" variant="outline">
38          <ToggleGroupItem value="grid" aria-label="Grid view">
39            <LayoutGrid className="h-5 w-5" />
40          </ToggleGroupItem>
41          <ToggleGroupItem value="list" aria-label="List view">
42            <LayoutList className="h-5 w-5" />
43          </ToggleGroupItem>
44          <ToggleGroupItem value="rows" aria-label="Rows view">
45            <Rows3 className="h-5 w-5" />
46          </ToggleGroupItem>
47        </ToggleGroup>
48      </div>
49    </div>
50  );
51}
52

با متن (With Text)

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

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
2import { AlignLeft, AlignCenter, AlignRight } from "lucide-react";
3
4export default function WithTextExample() {
5  return (
6    <ToggleGroup type="single" variant="outline" defaultValue="center">
7      <ToggleGroupItem value="right" aria-label="Align right">
8        <AlignRight className="ms-2 h-4 w-4" />
9        راست
10      </ToggleGroupItem>
11      <ToggleGroupItem value="center" aria-label="Align center">
12        <AlignCenter className="ms-2 h-4 w-4" />
13        وسط
14      </ToggleGroupItem>
15      <ToggleGroupItem value="left" aria-label="Align left">
16        <AlignLeft className="ms-2 h-4 w-4" />
17        چپ
18      </ToggleGroupItem>
19    </ToggleGroup>
20  );
21}
22

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

غیرفعال کردن کل گروه یا آیتم‌های خاص.

Group Disabled:

Item Disabled:

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
2import { Bold, Italic, Underline } from "lucide-react";
3
4export default function DisabledExample() {
5  return (
6    <div className="flex flex-col gap-4">
7      <div className="flex items-center gap-4">
8        <span className="text-sm font-medium w-32">Group Disabled:</span>
9        <ToggleGroup type="single" variant="outline" disabled>
10          <ToggleGroupItem value="bold" aria-label="Bold">
11            <Bold className="h-4 w-4" />
12          </ToggleGroupItem>
13          <ToggleGroupItem value="italic" aria-label="Italic">
14            <Italic className="h-4 w-4" />
15          </ToggleGroupItem>
16          <ToggleGroupItem value="underline" aria-label="Underline">
17            <Underline className="h-4 w-4" />
18          </ToggleGroupItem>
19        </ToggleGroup>
20      </div>
21      <div className="flex items-center gap-4">
22        <span className="text-sm font-medium w-32">Item Disabled:</span>
23        <ToggleGroup type="single" variant="outline">
24          <ToggleGroupItem value="bold" aria-label="Bold">
25            <Bold className="h-4 w-4" />
26          </ToggleGroupItem>
27          <ToggleGroupItem value="italic" aria-label="Italic" disabled>
28            <Italic className="h-4 w-4" />
29          </ToggleGroupItem>
30          <ToggleGroupItem value="underline" aria-label="Underline">
31            <Underline className="h-4 w-4" />
32          </ToggleGroupItem>
33        </ToggleGroup>
34      </div>
35    </div>
36  );
37}
38

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

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

گزینه‌های انتخاب شده را در کنسول مشاهده کنید

مشاهده کد

1import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
2import { Bold, Italic, Underline } from "lucide-react";
3
4export default function InteractiveExample() {
5  return (
6    <div className="space-y-4">
7      <ToggleGroup
8        type="multiple"
9        variant="outline"
10        onValueChange={(value) =>
11          console.log("Selected formatting:", value)
12        }
13      >
14        <ToggleGroupItem value="bold" aria-label="Bold">
15          <Bold className="ms-2 h-4 w-4" />
16          پررنگ
17        </ToggleGroupItem>
18        <ToggleGroupItem value="italic" aria-label="Italic">
19          <Italic className="ms-2 h-4 w-4" />
20          کج
21        </ToggleGroupItem>
22        <ToggleGroupItem value="underline" aria-label="Underline">
23          <Underline className="ms-2 h-4 w-4" />
24          زیرخط
25        </ToggleGroupItem>
26      </ToggleGroup>
27      <p className="text-sm text-muted-foreground">
28        گزینه‌های انتخاب شده را در کنسول مشاهده کنید
29      </p>
30    </div>
31  );
32}
33

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

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

ترکیب گروه‌های دکمه برای ساخت نوار ابزار ویرایشگر متن.

مشاهده کد

1import { useState } from "react";
2import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group";
3import { Bold, Italic, Underline, AlignLeft, AlignCenter, AlignRight } from "lucide-react";
4
5export default function FormattingToolbarExample() {
6  const [formatting, setFormatting] = useState<string[]>([]);
7  const [alignment, setAlignment] = useState("right");
8
9  return (
10    <div className="flex gap-2 p-2 border rounded-lg w-fit items-center">
11      <ToggleGroup
12        type="multiple"
13        value={formatting}
14        onValueChange={setFormatting}
15        variant="outline"
16        size="sm"
17      >
18        <ToggleGroupItem value="bold" aria-label="Bold">
19          <Bold className="h-4 w-4" />
20        </ToggleGroupItem>
21        <ToggleGroupItem value="italic" aria-label="Italic">
22          <Italic className="h-4 w-4" />
23        </ToggleGroupItem>
24        <ToggleGroupItem value="underline" aria-label="Underline">
25          <Underline className="h-4 w-4" />
26        </ToggleGroupItem>
27      </ToggleGroup>
28
29      <div className="w-px bg-border h-6" />
30
31      <ToggleGroup
32        type="single"
33        value={alignment}
34        onValueChange={setAlignment}
35        variant="outline"
36        size="sm"
37      >
38        <ToggleGroupItem value="right" aria-label="Align right">
39          <AlignRight className="h-4 w-4" />
40        </ToggleGroupItem>
41        <ToggleGroupItem value="center" aria-label="Align center">
42          <AlignCenter className="h-4 w-4" />
43        </ToggleGroupItem>
44        <ToggleGroupItem value="left" aria-label="Align left">
45          <AlignLeft className="h-4 w-4" />
46        </ToggleGroupItem>
47      </ToggleGroup>
48    </div>
49  );
50}
51

مرجع API (API Reference)

ToggleGroup

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

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`type`	`"single" \| "multiple"`	`undefined`	نوع انتخاب (تکی یا چندگانه)
`variant`	`"default" \| "outline" \| "ghost"`	`"default"`	نوع ظاهری گروه
`size`	`"sm" \| "md" \| "lg"`	`"md"`	اندازه گروه
`value`	`string \| string[]`	`undefined`	مقدار کنترل شده
`defaultValue`	`string \| string[]`	`undefined`	مقدار پیش‌فرض (غیرکنترل شده)
`onValueChange`	`(value) => void`	`undefined`	تابع فراخوانی هنگام تغییر مقدار
`disabled`	`boolean`	`false`	غیرفعال کردن کل گروه

ToggleGroupItem

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

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`value`	`string`	`-`	مقدار یکتای این آیتم
`disabled`	`boolean`	`false`	غیرفعال کردن این آیتم
`aria-label`	`string`	`-`	برچسب دسترسی‌پذیری

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

کیبورد (Keyboard)

Tab - حرکت به داخل/خارج گروه
Space یا Enter - تغییر وضعیت آیتم
Arrow Keys - حرکت بین آیتم‌ها
Home - رفتن به اولین آیتم
End - رفتن به آخرین آیتم

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

برای هر آیتم از aria-label استفاده کنید تا هدف واضح باشد

Roving Focus

گروه از الگوی roving tabindex برای مدیریت فوکوس استفاده می‌کند که تجربه کیبورد را بهبود می‌بخشد

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

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

Single: زمانی که فقط یک گزینه باید انتخاب شود (مثل تراز متن، نمای صفحه)
Multiple: زمانی که چندین گزینه می‌توانند همزمان فعال باشند (مثل قالب‌بندی متن)

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

همیشه aria-label معنادار برای هر آیتم فراهم کنید

آیکون‌ها (Icons)

از آیکون‌های واضح و شناخته شده استفاده کنید که هدف هر آیتم را مشخص کنند

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

آیتم‌های مرتبط را در یک گروه قرار دهید. برای دسته‌های مختلف از گروه‌های جداگانه استفاده کنید