Togglev1.0.1
دکمه‌ای که وضعیتش را نگه می‌دارد: یک بار کلیک روشن می‌شود، بار بعد خاموش. جایگزین فشرده‌ای برای چک‌باکس وقتی گزینه آیکونی است و در نوار ابزار می‌نشیند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/toggle.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/toggle.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/toggle.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/toggle.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { Toggle } from "@/components/ui/toggle"
<Toggle aria-label="برچسب">
<DigcheIcon file="Tag=linear.svg" />
</Toggle>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
کل ظاهر از toggleVariants می‌آید که همین فایل صادر می‌کند؛ گروه ضامن هم دقیقاً همین را وارد می‌کند، پس دکمهٔ تکی و دکمه‌های داخل گروه هیچ‌وقت از هم جدا نمی‌افتند.
اگر ظاهر تازه‌ای لازم دارید، variant را در همین cva اضافه کنید تا هر دو جا با هم عوض شوند.
برای انتخاب بین چند گزینه به‌جای چند Toggle مستقل از ToggleGroup استفاده کنید تا ناوبری صفحه‌کلید درست باشد.
دسترس‌پذیری
- حالت روشن با aria-pressed و data-state=on اعلام می‌شود؛ صفحه‌خوان «فشرده» یا «فشرده‌نشده» می‌خواند.
- دکمه‌ای که فقط آیکون دارد حتماً باید aria-label بگیرد.
- با Space و Enter تغییر حالت می‌دهد، دقیقاً مثل یک دکمهٔ معمولی.
- اگر گزینه بخشی از یک فرم است و باید ارسال شود، چک‌باکس انتخاب درست‌تری است؛ Toggle مقدار فرم نمی‌فرستد.
مرجع API
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" | ارتفاع و حداقل عرض دکمه. سه‌تای icon* مربع‌اند و برای دکمهٔ فقط‌آیکونی‌اند (بدون پدینگ افقی). |
| disabled | boolean | false | غیرفعال کردن دکمه. |
| asChild | boolean | false | رفتار ضامن را روی فرزند سوار می‌کند. |
toggleVariants
همان cva استایل‌ها؛ گروه ضامن و هر کامپوننت دیگری که بخواهد ظاهر یکسان بدهد از این وارد می‌کند.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| toggleVariants({ variant, size }) | (props) => string | — | رشتهٔ کلاس‌ها را برمی‌گرداند؛ با cn روی عنصر دلخواه بگذارید. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
Variants
حالت پیش‌فرض بدون کادر است و outline کادر و سایهٔ خفیف دارد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Sizes
سه اندازه دارد؛ آیکون‌ها خودکار size-4 می‌گیرند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Icon Only
اندازه‌های icon/icon-sm/icon-lg مربع کامل‌اند و پدینگ افقی ندارند؛ برای وقتی متن کنار آیکون نیست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
With Text
متن کنار آیکون هم می‌نشیند؛ برای گزینه‌هایی که آیکون به‌تنهایی گویا نیست.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
در حالت غیرفعال نه کلیک می‌گیرد و نه فوکوس.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Toggle یا Switch
هر دو دو حالت دارند ولی جایشان یکی نیست. Toggle ابزارِ نوار ابزار است و اثرش روی چیزی است که همین حالا انتخاب شده، مثل پررنگ‌کردن متن. Switch تنظیمی ماندگار است، لیبل جدا دارد و بعد از رفتن از صفحه هم می‌ماند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
غیرفعال با دلیل (Disabled)
دکمهٔ خاموشِ بی‌توضیح، کاربر را به کلیک‌های بی‌نتیجه وامی‌دارد. دلیل را کنارش بنویسید و با aria-describedby وصلش کنید تا صفحه‌خوان هم بخواند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال اعمال (Loading)
وضعیت را بلافاصله عوض نکنید. اگر درخواست شکست بخورد، دکمه چیزی را نشان می‌دهد که واقعاً ذخیره نشده. تا رسیدن پاسخ، دکمه قفل و aria-busy روشن است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| Variants | حالت پیش‌فرض بدون کادر است و outline کادر و سایهٔ خفیف دارد. |
| Sizes | سه اندازه دارد؛ آیکون‌ها خودکار size-4 می‌گیرند. |
| Icon Only | اندازه‌های icon/icon-sm/icon-lg مربع کامل‌اند و پدینگ افقی ندارند؛ برای وقتی متن کنار آیکون نیست. |
| With Text | متن کنار آیکون هم می‌نشیند؛ برای گزینه‌هایی که آیکون به‌تنهایی گویا نیست. |
| Disabled | در حالت غیرفعال نه کلیک می‌گیرد و نه فوکوس. |
| Toggle یا Switch | تصمیم اول: این دو حالت، ابزار است یا تنظیم |
| غیرفعال با دلیل (Disabled) | ابزاری که برای محتوای انتخاب‌شده معنا ندارد |
| در حال اعمال (Loading) | تنظیمی که با هر تغییر به سرور می‌رود |
دستورالعمل استفاده
برچسب دسترس‌پذیر برای دکمهٔ فقط‌آیکونی
انجام بده
هر ضامنی که فقط آیکون دارد باید aria-label بگیرد؛ وگرنه صفحه‌خوان چیزی برای خواندن ندارد و کاربر نمی‌فهمد این دکمه چه می‌کند.
انجام نده
آیکون به‌تنهایی برای صفحه‌خوان معنا ندارد؛ کاربر فقط «دکمهٔ فشرده‌نشده» می‌شنود.
برای انتخاب بین چند گزینه، گروه ضامن
انجام بده
وقتی گزینه‌ها به هم مربوط‌اند و باید یکی انتخاب شود، از ToggleGroup استفاده کنید تا ناوبری با کلیدهای جهت‌دار و رابطهٔ گزینه‌ها درست باشد.
انجام نده
چند Toggle مستقل کنار هم، از نظر صفحه‌کلید و صفحه‌خوان سه دکمهٔ بی‌ربط‌اند؛ نه ناوبری گروهی دارند و نه معلوم است انتخاب‌ها به هم مربوط‌اند.
برای مقدارِ فرم، چک‌باکس
انجام بده
اگر گزینه باید با فرم ارسال شود یا در فهرست تنظیمات با برچسب متنی بنشیند، چک‌باکس ابزار درست است؛ Toggle مقدار فرم نمی‌فرستد.
انجام نده
ضامنِ فقط‌آیکونی برای یک تنظیم مهم، هم معنایش پنهان است و هم در فرم ارسال نمی‌شود؛ کاربر باید حدس بزند این آیکون چه چیزی را روشن می‌کند.