Radio Group
گروهی از گزینهها که کاربر فقط یکی از آنها را انتخاب میکند.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/radio-group.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/radio-group.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/radio-group.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/radio-group.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
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 پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
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" | چیدمان گزینهها زیر هم یا کنار هم. |
| 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. |
| disabled | boolean | false | غیرفعال کردن گزینه؛ مقدار گروه را نادیده میگیرد. |
| readOnly | boolean | — | جلوی انتخاب همین گزینه را میگیرد؛ نبود آن یعنی از readOnly گروه ارث میبرد. |
| invalid | boolean | — | وضعیت نامعتبر همین گزینه؛ نبود آن یعنی از invalid گروه ارث میبرد. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
نامعتبر (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 پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| نامعتبر (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 قابلدسترسی میماند.
روش ارسال: ارسال سریع
انجام نده
پنهانکردن گروه و نمایش فقط متن انتخابشده، وضعیت را از فرم واقعی جدا میکند و اگر کاربر انتظار یک فیلد فرم را داشته باشد گیجکننده است.