Radio Groupv1.0.1
گروهی از گزینه‌ها که کاربر فقط یکی از آن‌ها را انتخاب می‌کند.
این کامپوننت فعلاً برای ۱ فریم‌ورک از ۴ فریم‌ورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نصب
با CLI اختصاصی digdesign کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگی‌ها و فایل‌ها خودکار اضافه می‌شوند.
npx digdesign@latest add https://docs.digdesign.ir/r/radio-group.jsonpnpm dlx digdesign@latest add https://docs.digdesign.ir/r/radio-group.jsonyarn dlx digdesign@latest add https://docs.digdesign.ir/r/radio-group.jsonbunx --bun digdesign@latest add https://docs.digdesign.ir/r/radio-group.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
استفاده
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"
import { Label } from "@/components/ui/label"
<RadioGroup defaultValue="a">
<RadioGroupItem value="a" id="a" />
<Label htmlFor="a">گزینهٔ یک</Label>
<RadioGroupItem value="b" id="b" />
<Label htmlFor="b">گزینهٔ دو</Label>
</RadioGroup>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
ترکیب اجزا
disabled/invalid/required/readOnly روی خودِ RadioGroup به‌صورت پیش‌فرض به همهٔ گزینه‌ها می‌رسد؛ هر RadioGroupItem می‌تواند invalid یا readOnly خودش را جداگانه هم بدهد تا این پیش‌فرض را نادیده بگیرد.
دسترس‌پذیری
- ناوبری بین گزینه‌ها با کلیدهای جهت‌نما انجام می‌شود (roving tabindex).
- هر RadioGroupItem را با Label و id متصل کنید تا با کلیک روی متن هم انتخاب شود.
- readOnly برخلاف disabled، گزینه را از چرخهٔ Tab و صفحه‌خوان حذف نمی‌کند؛ فقط جلوی تغییر مقدار را می‌گیرد.
- invalid مقدار aria-invalid را ست می‌کند تا صفحه‌خوان وضعیت نامعتبر را همراه با متن خطای کنارش اعلام کند.
- required مقدار aria-required را روی نقش radiogroup می‌گذارد، نه روی یک گزینهٔ خاص.
مرجع API
RadioGroup
چند RadioGroupItem را با یک مقدار انتخاب‌شده هماهنگ می‌کند؛ خودش نقش radiogroup می‌گیرد.
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value / defaultValue | string | — | گزینهٔ انتخاب‌شده (کنترل‌شده یا اولیه). |
| onValueChange | (value: string) => void | — | با تغییر انتخاب صدا زده می‌شود. |
| orientation | "horizontal" | "vertical" | "vertical" | چیدمان گزینه‌ها زیر هم یا کنار هم. |
| name | string | — | نام فیلد در فرم. گزینه‌ها دکمه‌اند نه input، پس بدون name مقدار با submit بومی یا FormData ارسال نمی‌شود؛ با name یک input مخفی هم‌نام مقدار انتخاب‌شده را می‌فرستد. |
| form | string | — | شناسهٔ فرم، وقتی گروه بیرون از تگ form است. |
| interaction | "none" | "press" | "pop" | "peek" | "none" | اینتراکشن پیش‌فرض همهٔ گزینه‌های گروه: press کوچک شدن هنگام فشردن، pop ظاهر شدن نقطه با جهش، peek پیش‌نمایش نقطه روی هاور. |
| disabled | boolean | false | پیش‌فرض همهٔ گزینه‌ها را غیرفعال می‌کند؛ هر گزینه می‌تواند با disabled={false} این را نادیده بگیرد. |
| readOnly | boolean | false | کل گروه را از تغییر مقدار باز می‌دارد ولی برخلاف disabled، ظاهر عادی و چرخهٔ Tab را حفظ می‌کند. |
| invalid | boolean | false | پیش‌فرض همهٔ گزینه‌ها را در حالت نامعتبر نشان می‌دهد. |
| required | boolean | false | aria-required روی نقش radiogroup می‌گذارد. |
RadioGroupItem
| ویژگی | نوع | پیش‌فرض | توضیح |
|---|---|---|---|
| value | string | — | مقدار یکتای این گزینه. |
| variant | "default" | "flat" | "default" | default سایه‌دار است؛ flat بدون سایه و با پس‌زمینهٔ خاکستری خنثی، برای داخل کارت یا Surface. |
| interaction | "none" | "press" | "pop" | "peek" | "none" | واکنش به فشردن و هاور: press کوچک شدن هنگام فشردن، pop ظاهر شدن علامت با جهش، peek پیش‌نمایش علامت روی هاور. روی disabled و readOnly اعمال نمی‌شود. بدون مقدار، از RadioGroup ارث می‌برد. |
| disabled | boolean | false | غیرفعال کردن گزینه؛ مقدار گروه را نادیده می‌گیرد. |
| readOnly | boolean | — | جلوی انتخاب همین گزینه را می‌گیرد؛ نبود آن یعنی از readOnly گروه ارث می‌برد. |
| invalid | boolean | — | وضعیت نامعتبر همین گزینه؛ نبود آن یعنی از invalid گروه ارث می‌برد. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ری‌اکت آماده است؛ پورت این فریم‌ورک در دست کار است.
نمونه‌ها
ارسال با فرم (name)
با name، مقدار انتخاب‌شده مثل یک input معمولی همراه فرم ارسال می‌شود. بدون آن، RadioGroup فقط state داخلی دارد و فرم بی‌صدا بدون این فیلد ارسال می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
اینتراکشن (interaction)
واکنش گزینه‌ها به فشردن و هاور. معمولاً روی خود RadioGroup داده می‌شود تا همهٔ گزینه‌ها یکسان رفتار کنند. peek نقطه را روی هاور پیش‌نمایش می‌کند تا معلوم باشد کدام گزینه انتخاب خواهد شد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
نامعتبر (Invalid)
برای خطای اعتبارسنجی فرم، invalid را روی خودِ RadioGroup بدهید؛ حاشیهٔ همهٔ گزینه‌ها و نقطهٔ گزینهٔ انتخاب‌شده قرمز می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
فقط‌خواندنی (Read-only)
برخلاف disabled، readOnly ظاهر عادی را حفظ می‌کند و در چرخهٔ Tab می‌ماند؛ فقط جلوی تغییر مقدار با کلیک یا کیبورد را می‌گیرد.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Variant: default و flat
variant="flat" سایه ندارد و پس‌زمینهٔ خاکستری خنثی می‌گیرد، برای وقتی گزینه‌ها داخل یک کارت یا Surface هستند که خودش سایه یا حاشیه دارد و سایهٔ پیش‌فرض روی هم تلنبار می‌شود.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
چیدمان افقی (orientation)
برای گروه‌های کوتاه مثل بله/خیر، orientation="horizontal" گزینه‌ها را در یک ردیف کنار هم می‌چیند به‌جای زیر هم.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
با توضیح زیرِ گزینه
برای گزینه‌ای که به توضیح بیشتری نیاز دارد، یک متن کوچک زیرش با تورفتگی هم‌تراز با متن Label بگذارید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
Disabled
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
در حال ذخیره (Loading)
کل گروه را قفل کنید، نه فقط گزینهٔ انتخاب‌شده؛ وگرنه کاربر می‌تواند وسط درخواستِ قبلی گزینهٔ دیگری بزند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه می‌بینید نسخهٔ ری‌اکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار می‌آید |
|---|---|
| ارسال با فرم (name) | فرمی که با action یا FormData ارسال می‌شود، نه با state |
| اینتراکشن (interaction) | واکنش گزینه‌ها به فشردن و هاور |
| نامعتبر (Invalid) | برای خطای اعتبارسنجی فرم، invalid را روی خودِ RadioGroup بدهید؛ حاشیهٔ همهٔ گزینه‌ها و نقطهٔ گزینهٔ انتخاب‌شده قرمز می‌شود. |
| فقط‌خواندنی (Read-only) | برخلاف disabled، readOnly ظاهر عادی را حفظ می‌کند و در چرخهٔ Tab می‌ماند؛ فقط جلوی تغییر مقدار با کلیک یا کیبورد را می‌گیرد. |
| Variant: default و flat | variant="flat" سایه ندارد و پس‌زمینهٔ خاکستری خنثی می‌گیرد، برای وقتی گزینه‌ها داخل یک کارت یا Surface هستند که خودش سایه یا حاشیه دارد و سایهٔ پیش‌فرض روی هم تلنبار می‌شود. |
| چیدمان افقی (orientation) | برای گروه‌های کوتاه مثل بله/خیر، orientation="horizontal" گزینه‌ها را در یک ردیف کنار هم می‌چیند به‌جای زیر هم. |
| با توضیح زیرِ گزینه | برای گزینه‌ای که به توضیح بیشتری نیاز دارد، یک متن کوچک زیرش با تورفتگی هم‌تراز با متن Label بگذارید. |
| Disabled | روش ارسالی که برای آدرس فعلی کاربر در دسترس نیست |
| در حال ذخیره (Loading) | انتخابی که با هر تغییر به سرور می‌رود |
دستورالعمل استفاده
تعداد کم گزینه، همه هم‌زمان قابل مشاهده
انجام بده
برای دو تا پنج گزینهٔ متقابلاً منحصر به‌فرد که باید همه با هم دیده شوند (مثل روش ارسال)، RadioGroup مناسب‌ترین انتخاب است.
انجام نده
برای فهرست‌های بلند (مثل انتخاب استان) RadioGroup فضای زیادی اشغال می‌کند و اسکرول را طولانی می‌کند؛ در این حالت‌ها از Select استفاده کنید.
همیشه یک گزینهٔ انتخاب‌شده
انجام بده
با value یا defaultValue یک گزینهٔ منطقی و پیش‌فرض تعیین کنید تا فرم هیچ‌وقت در حالت «هیچ‌کدام انتخاب نشده» نماند.
انجام نده
رها کردن گروه بدون مقدار اولیه یعنی کاربر باید حتماً یکی را دستی انتخاب کند تا فرم معتبر شود؛ این تجربه را کندتر می‌کند.
disabled یا readOnly، نه اینکه گزینه ناپدید شود
انجام بده
برای نمایش یک فرم ثبت‌شده که کاربر نباید تغییرش دهد ولی باید مقدار واقعی را ببیند، readOnly روی کل گروه مقدار را ثابت نگه می‌دارد و همچنان با Tab قابل‌دسترسی می‌ماند.
روش ارسال: ارسال سریع
انجام نده
پنهان‌کردن گروه و نمایش فقط متن انتخاب‌شده، وضعیت را از فرم واقعی جدا می‌کند و اگر کاربر انتظار یک فیلد فرم را داشته باشد گیج‌کننده است.