Toggle Groupv1.0.0
دکمه‌ای که روشن و خاموش می‌ماند (Toggle) و گروهی از همین دکمه‌ها که کنار هم می‌نشینند (ToggleGroup). برای نوار ابزار ویرایشگر، انتخاب حالت نمایش و هر جایی که گزینه‌ها آیکونی و کوتاه‌اند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/toggle-group.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/toggle-group.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/toggle-group.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/toggle-group.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Toggle } from "@/components/ui/toggle"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
// دکمهٔ دوحالتهٔ تکی
<Toggle aria-label="برچسب">
<DigcheIcon file="Tag=linear.svg" />
</Toggle>
// گروه تک‌انتخابی
<ToggleGroup type="single" defaultValue="center">
<ToggleGroupItem value="right" aria-label="شبکه‌ای">
<DigcheIcon file="Gridview=linear.svg" />
</ToggleGroupItem>
<ToggleGroupItem value="center" aria-label="شبکه‌ای فشرده">
<DigcheIcon file="GridviewSquare=linear.svg" />
</ToggleGroupItem>
</ToggleGroup>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
ToggleGroup استایلش را از toggleVariants فایل Toggle می‌گیرد، پس دکمهٔ تکی و گروه همیشه یک شکل‌اند و رجیستری هم توگل را همراه گروه نصب می‌کند.
variant و size را روی خود گروه بگذارید؛ از طریق کانتکست به همهٔ آیتم‌ها می‌رسد و لازم نیست روی تک‌تکشان تکرار شود (اگر روی یک آیتم هم بدهید، مقدار گروه برنده است).
گِرد شدن گوشه‌ها و ادغام حاشیه با کلاس‌های منطقی rtl-آگاه انجام می‌شود و با orientation هماهنگ است (start/end در حالت افقی، بالا/پایین در حالت عمودی)، پس با چرخش جهت صفحه یا تغییر چیدمان، اولین و آخرین دکمه خودشان جای درست را می‌گیرند.
separated این ادغام را کنار می‌گذارد و هر دکمه گوشهٔ گرد و فاصلهٔ خودش را می‌گیرد.
دسترس‌پذیری
- گروه role=toolbar با ناوبری roving focus است: با Tab یک‌بار وارد گروه می‌شوید و با کلیدهای جهت‌دار (و Home/End) بین دکمه‌ها حرکت می‌کنید، نه با Tab. با rovingFocus={false} این رفتار خاموش می‌شود و هر دکمه جداگانه با Tab فوکوس می‌گیرد.
- جهت کلیدهای جهت‌دار با orientation عوض می‌شود (چپ/راست برای horizontal، بالا/پایین برای vertical) و در حالت افقی از نزدیک‌ترین dir در DOM می‌خواند؛ برای همین dir="rtl" را روی html نگه دارید تا در راست‌به‌چپ برعکس نشود. برای رفتار متفاوت از dir صفحه، پراپ dir را مستقیم بدهید.
- هر دکمه‌ای که فقط آیکون دارد باید aria-label داشته باشد؛ بدون آن صفحه‌خوان چیزی برای خواندن ندارد.
- حالت روشن با data-state=on و aria-pressed مشخص می‌شود؛ اتکا به تفاوت رنگ به‌تنهایی کافی نیست، از آیکون یا متن گویا استفاده کنید.
- اگر انتخاب یکی از گزینه‌ها اجباری است، از type="single" همراه با مقدار پیش‌فرض و disallowEmptySelection استفاده کنید تا حالت «هیچ‌کدام» اصلاً پیش نیاید.
مرجع API
ToggleGroup
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| type | "single" | "multiple" | — | الزامی. single یعنی حداکثر یک گزینهٔ فعال و multiple یعنی هر تعداد. |
| value / onValueChange | string | string[] / (value) => void | — | کنترل‌شده؛ در حالت multiple نوع مقدار آرایهٔ رشته است. |
| defaultValue | string | string[] | — | مقدار اولیه در حالت کنترل‌نشده. |
| variant | "default" | "outline" | "segmented" | "default" | روی گروه بگذارید تا از کانتکست به همهٔ آیتم‌ها برسد. |
| size | "sm" | "default" | "lg" | "icon-sm" | "icon" | "icon-lg" | "default" | اندازهٔ همهٔ آیتم‌های گروه. |
| disabled | boolean | false | غیرفعال کردن کل گروه. |
| disallowEmptySelection | boolean | false | جلوی خالی‌شدنِ کامل انتخاب را می‌گیرد. در single یعنی نمی‌شود گزینهٔ فعال را با کلیک دوباره خاموش کرد؛ در multiple یعنی آخرین گزینهٔ روشن را نمی‌شود خاموش کرد. |
| orientation | "horizontal" | "vertical" | "horizontal" | چیدمان دکمه‌ها و جهت کلیدهای جهت‌دار؛ گِردشدن گوشه‌ها هم با آن هماهنگ می‌شود. |
| separated | boolean | false | به‌جای دکمه‌های به‌هم‌چسبیده، هر دکمه گوشهٔ گرد و فاصلهٔ خودش را می‌گیرد، برای نوار ابزاری که نباید شکل کنترل تک‌پارچه بدهد. |
| fullWidth | boolean | false | دکمه‌ها به‌اندازهٔ مساوی فضای موجود را پر می‌کنند؛ در orientation="vertical" یعنی ارتفاع کامل. |
| rovingFocus | boolean | true | ناوبری با کلیدهای جهت‌دار؛ با false هر دکمه با Tab فوکوس می‌گیرد. |
| loop | boolean | true | رسیدن به انتهای گروه دوباره به ابتدا برمی‌گردد. |
| dir | "rtl" | "ltr" | — | جهت ناوبری کلیدها؛ معمولاً از dir صفحه (html) ارث می‌رسد. |
ToggleGroupItem
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | الزامی و یکتا؛ همان مقداری که در value گروه می‌آید. |
| disabled | boolean | false | فقط همین آیتم را غیرفعال می‌کند. |
| variant / size | "default" | "outline" | "segmented" / "sm" | "default" | "lg" | "icon-sm" | "icon" | "icon-lg" | — | اگر روی گروه ست شده باشد، مقدار گروه اولویت دارد؛ این‌ها برای آیتم‌های خارج از گروه‌اند. |
Toggle
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| pressed / onPressedChange | boolean / (pressed: boolean) => void | — | حالت کنترل‌شدهٔ روشن و خاموش. |
| defaultPressed | boolean | false | حالت اولیه در وضعیت کنترل‌نشده. |
| variant | "default" | "outline" | "segmented" | "default" | بدون حاشیه یا با حاشیه و سایهٔ خفیف. |
| size | "sm" | "default" | "lg" | "icon-sm" | "icon" | "icon-lg" | "default" | اندازهٔ دکمه؛ آیکون‌ها خودکار size-4 می‌گیرند. سه‌تای icon* مربع‌اند و برای دکمهٔ فقط‌آیکونی‌اند. |
| disabled | boolean | false | غیرفعال کردن دکمه. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Single Selection
با type="single" فقط یک گزینه فعال می‌ماند؛ مثل دکمهٔ رادیویی ولی فشرده‌تر.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
With Text
آیتم‌ها متن هم می‌پذیرند؛ برای گزینه‌هایی که آیکون گویایی ندارند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Sizes and Variants
variant و size روی گروه می‌نشینند و به همهٔ آیتم‌ها ارث می‌رسند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Single Toggle
برای یک گزینهٔ مستقل، Toggle را بدون گروه به کار ببرید؛ همان variant و size را می‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Orientation
orientation="vertical" دکمه‌ها را زیر هم می‌چیند و کلیدهای بالا/پایین بین‌شان حرکت می‌کنند؛ گوشه‌های گرد هم خودکار با چیدمان هماهنگ می‌شوند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Separated
با separated دکمه‌ها گوشهٔ گرد و فاصلهٔ خودشان را می‌گیرند به‌جای شکل کنترل تک‌پارچه؛ منطق انتخاب همان می‌ماند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Full Width
دکمه‌ها به‌اندازهٔ مساوی فضای موجود را پر می‌کنند؛ برای تب‌های تمام‌عرض یا سوییچر حالت نمایش.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disallow Empty Selection
برای گزینه‌هایی مثل نمای نمایش که همیشه باید یک مقدار فعال داشته باشد؛ کلیک روی گزینهٔ فعال آن را خاموش نمی‌کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
disabled را روی کل گروه یا روی یک آیتم بگذارید؛ آیتم غیرفعال از ناوبری صفحه‌کلید هم خارج می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال اعمال (Loading)
کل گروه را قفل کنید تا کاربر وسط ذخیره گزینهٔ دیگری نزند؛ وگرنه دو درخواست همزمان می‌رود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Single Selection | با type="single" فقط یک گزینه فعال می‌ماند؛ مثل دکمهٔ رادیویی ولی فشرده‌تر. |
| With Text | آیتم‌ها متن هم می‌پذیرند؛ برای گزینه‌هایی که آیکون گویایی ندارند. |
| Sizes and Variants | variant و size روی گروه می‌نشینند و به همهٔ آیتم‌ها ارث می‌رسند. |
| Single Toggle | برای یک گزینهٔ مستقل، Toggle را بدون گروه به کار ببرید؛ همان variant و size را می‌گیرد. |
| Orientation | orientation="vertical" دکمه‌ها را زیر هم می‌چیند و کلیدهای بالا/پایین بین‌شان حرکت می‌کنند؛ گوشه‌های گرد هم خودکار با چیدمان هماهنگ می‌شوند. |
| Separated | با separated دکمه‌ها گوشهٔ گرد و فاصلهٔ خودشان را می‌گیرند به‌جای شکل کنترل تک‌پارچه؛ منطق انتخاب همان می‌ماند. |
| Full Width | دکمه‌ها به‌اندازهٔ مساوی فضای موجود را پر می‌کنند؛ برای تب‌های تمام‌عرض یا سوییچر حالت نمایش. |
| Disallow Empty Selection | برای گزینه‌هایی مثل نمای نمایش که همیشه باید یک مقدار فعال داشته باشد؛ کلیک روی گزینهٔ فعال آن را خاموش نمی‌کند. |
| Disabled | disabled را روی کل گروه یا روی یک آیتم بگذارید؛ آیتم غیرفعال از ناوبری صفحه‌کلید هم خارج می‌شود. |
| در حال اعمال (Loading) | چیدمانی که با هر تغییر ذخیره می‌شود |
دستورالعمل استفاده
نوع گروه را با ماهیت انتخاب هماهنگ کنید
انجام بده
برای گزینه‌های ناسازگار (نمای نمایش که فقط یکی می‌تواند فعال باشد) type=«single» بدهید و یک مقدار پیش‌فرض بگذارید تا حالت «هیچ‌کدام» پیش نیاید.
انجام نده
با type=«multiple» کاربر می‌تواند همزمان نمای شبکه‌ای و نمای فهرستی را همزمان روشن کند؛ حالتی که در واقعیت وجود ندارد و رابط را متناقض نشان می‌دهد.
ظاهر را روی گروه بگذارید، نه تک‌تک آیتم‌ها
انجام بده
variant و size روی ToggleGroup می‌نشینند و از کانتکست به همهٔ آیتم‌ها می‌رسند؛ گروه یکدست می‌ماند و اضافه‌کردن آیتم تازه چیزی را خراب نمی‌کند.
انجام نده
دادن اندازه و حالت جدا به هر آیتم، هم تکراری است و هم به‌راحتی ناهماهنگ می‌شود، مقدار گروه در هر حال برنده است و این تنظیم‌ها نادیده می‌مانند.
برچسب برای آیتم‌های آیکونی
انجام بده
هر ToggleGroupItem که فقط آیکون دارد باید aria-label بگیرد؛ در نوار ابزار، آیکون‌ها برای صفحه‌خوان بی‌نام‌اند.
انجام نده
بدون برچسب، کاربر صفحه‌خوان فقط «دکمهٔ فشرده‌نشده» می‌شنود و نمی‌داند کدام چیدمان را انتخاب می‌کند.