لیست کشویی
انتخاب یک یا چند گزینه از فهرستی از موارد. محتوای منو با dir="rtl" رندر میشود تا نشانگر انتخاب و چیدمان آیتمها همجهت باقی بماند.
این کامپوننت فعلاً برای ۱ فریمورک از ۴ فریمورک آماده است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نصب
با CLI اختصاصی dig-ui کامپوننت را از رجیستری دیگ نصب کنید؛ وابستگیها و فایلها خودکار اضافه میشوند.
pnpm dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/select.jsonnpx dig-ui@latest add https://design-system-tau-green.vercel.app/r/select.jsonyarn dlx dig-ui@latest add https://design-system-tau-green.vercel.app/r/select.jsonbunx --bun dig-ui@latest add https://design-system-tau-green.vercel.app/r/select.jsonاین کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
استفاده
import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from "@/components/ui/select"
<Select>
<SelectTrigger>
<SelectValue placeholder="انتخاب کنید" />
</SelectTrigger>
<SelectContent>
<SelectItem value="a">گزینه ۱</SelectItem>
</SelectContent>
</Select>این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
ترکیب اجزا
Select از Trigger (دکمهی بازکننده)، Value (نمایش انتخاب فعلی)، Content (پوشش شناور) و Itemها تشکیل شده.
SelectGroup و SelectLabel برای دستهبندی گزینهها، و SelectItemDescription برای زیرمتن توضیحی زیر هر گزینه، اختیاری هستند.
دسترسپذیری
- با کلیدهای جهتدار بالا/پایین بین گزینهها حرکت میکند و با تایپ حروف، به گزینهٔ همنام میپرد.
- چون <html> پیشفرض dir="rtl" دارد و خودِ کامپوننت این جهت را از نزدیکترین [dir] میخواند، ناوبری با صفحهکلید و محل باز شدن منو همجهت با RTL است.
- در حالت چندانتخابی (multiple)، role روی فهرست به aria-multiselectable مجهز میشود و انتخاب هر گزینه فهرست را نمیبندد تا کاربر بتواند چند گزینه را پشتسرهم انتخاب کند.
مرجع API
Select
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| dir | "rtl" | "ltr" | "rtl" | جهت باز شدن و چیدمان محتوای منو. |
| multiple | boolean | false | فعالسازی حالت چندانتخابی؛ در این حالت value/defaultValue/onValueChange بهجای string از نوع string[] هستند. |
| value | string | string[] | — | مقدار کنترلشده، رشته در حالت تکانتخابی، آرایه در حالت چندانتخابی (multiple). |
| defaultValue | string | string[] | — | مقدار اولیهٔ انتخابشده در حالت کنترلنشده، نوعش همراستا با multiple است. |
| onValueChange | (value: string) => void | (value: string[]) => void | — | فراخوانی هنگام تغییر گزینهٔ انتخابشده. |
| open | boolean | — | حالت باز/بستهٔ کنترلشدهٔ فهرست. |
| defaultOpen | boolean | false | حالت اولیهٔ باز/بسته در حالت کنترلنشده. |
| onOpenChange | (open: boolean) => void | — | فراخوانی هنگام تغییر حالت باز/بستهٔ فهرست. |
| disabled | boolean | false | غیرفعال کردن کل لیست کشویی. |
SelectValue
| ویژگی | نوع | پیشفرض | توضیح |
|---|---|---|---|
| chips | boolean | false | فقط در حالت چندانتخابی: هر گزینهٔ انتخابشده را بهجای متن بههمچسبیده، بهشکل چیپ نشان میدهد. |
| placeholder | ReactNode | — | متن جایگزین وقتی چیزی انتخاب نشده. |
این کامپوننت هنوز برای Vue پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Reka UI در دست کار است.
این کامپوننت هنوز برای Svelte پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Bits UI در دست کار است.
این کامپوننت هنوز برای Angular پورت نشده است.
نسخهٔ ریاکت آماده است؛ پورت این فریمورک روی Angular CDK در دست کار است.
نمونهها
Grouped with Labels
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
Disabled
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
چندانتخابی
با prop مربوط به multiple، بهجای یک مقدار رشتهای، آرایهای از مقادیر انتخاب میشود؛ فهرست پس از هر انتخاب باز میماند و نشانگر تیک بهجای انتهای گزینه، ابتدای آن مینشیند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
چندانتخابی بهشکل چیپس
با پراپ chips روی SelectValue، بهجای متنِ بههمچسبیده، هر گزینهٔ انتخابشده یک چیپ جداگانه میشود. چون تعداد چیپها میتواند به سطر بعد برود، روی Trigger هم ارتفاع را با h-auto py-1.5 آزاد بگذارید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
با توضیح زیر گزینه
SelectItemDescription یک زیرمتن کمرنگ زیر برچسب هر گزینه اضافه میکند؛ چون در Trigger نمایش داده نمیشود، برای گزینههایی که نیاز به توضیح کوتاه دارند (مثل پلنهای قیمتگذاری) مناسب است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
باز/بستهٔ کنترلشده
با open، defaultOpen و onOpenChange میتوانید حالت باز/بسته را از بیرونِ کامپوننت مدیریت کنید، مثلاً باز کردن فهرست با یک دکمهٔ دیگر.
لیست کشویی بسته است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
نامعتبر (Invalid)
با aria-invalid حاشیه و حلقهٔ فوکوس قرمز میشود. پیام خطا را با aria-describedby به تریگر وصل کنید تا صفحهخوان هم آن را بخواند.
انتخاب دسته الزامی است.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
غیرفعال در برابر فقطخواندنی
Select حالت readOnly ندارد و disabled جای آن نیست: مقدارِ غیرفعال خاکستری و غیرقابل کپی میشود. اگر مقدار قطعی شده و فقط باید دیده شود، بهجای کنترل، متن نشان دهید.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
در حال دریافت گزینهها (Loading)
تا رسیدن گزینهها تریگر را قفل کنید و placeholder را گویا بگذارید. aria-busy به صفحهخوان میگوید منتظر است. باز شدن فهرست خالی، کاربر را گمراه میکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
فهرست خالی (Empty)
فهرست خالی نباید یک کادر خالی باشد. بگویید چرا خالی است و کاربر برای پرکردنش باید چه کند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
متن بلند (Overflow)
نامهای فارسی بلندند. تریگر را عرض ثابت بدهید تا مقدار با line-clamp کوتاه شود؛ متن کامل داخل فهرست دیده میشود. بدون عرض ثابت، تریگر با محتوا کش میآید و چیدمان فرم میشکند.
این نمونه هنوز برای Vue پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Svelte پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
این نمونه هنوز برای Angular پورت نشده است؛ آنچه میبینید نسخهٔ ریاکت است.
کدام نمونه برای کدام موقعیت
| نمونه | کجا به کار میآید |
|---|---|
| Grouped with Labels | فهرست شهرها یا دستهبندیهای تودرتو که زیرمجموعهٔ یک استان/دستهاند |
| Disabled | فیلدی که به انتخاب قبلیِ کاربر در فرم بستگی دارد |
| چندانتخابی | با prop مربوط به multiple، بهجای یک مقدار رشتهای، آرایهای از مقادیر انتخاب میشود؛ فهرست پس از هر انتخاب باز میماند و نشانگر تیک بهجای انتهای گزینه، ابتدای آن مینشیند. |
| چندانتخابی بهشکل چیپس | با پراپ chips روی SelectValue، بهجای متنِ بههمچسبیده، هر گزینهٔ انتخابشده یک چیپ جداگانه میشود |
| با توضیح زیر گزینه | SelectItemDescription یک زیرمتن کمرنگ زیر برچسب هر گزینه اضافه میکند؛ چون در Trigger نمایش داده نمیشود، برای گزینههایی که نیاز به توضیح کوتاه دارند (مثل پلنهای قیمتگذاری) مناسب است. |
| باز/بستهٔ کنترلشده | با open، defaultOpen و onOpenChange میتوانید حالت باز/بسته را از بیرونِ کامپوننت مدیریت کنید، مثلاً باز کردن فهرست با یک دکمهٔ دیگر. |
| نامعتبر (Invalid) | فرمی که کاربر بدون انتخاب، دکمهٔ ثبت را زده |
| غیرفعال در برابر فقطخواندنی | فیلدی که بعد از تایید نهایی قفل شده و فقط باید دیده شود |
| در حال دریافت گزینهها (Loading) | فهرستی که از سرور میآید |
| فهرست خالی (Empty) | کاربر تازهای که هنوز موردی ندارد |
| متن بلند (Overflow) | عنوان بلند در فرم چندستونی |
دستورالعمل استفاده
برچسب کوتاه برای گزینهها
انجام بده
متن هر SelectItem را کوتاه و اسکنپذیر نگه دارید؛ چون متن گزینهٔ انتخابشده در Trigger با line-clamp به یک خط محدود میشود.
انجام نده
یک جملهٔ کامل را داخل متن گزینه نچپانید؛ هم در Trigger بریده میشود و هم در لیست باز خواندنش سخت است.
دستهبندی فهرستهای بلند
انجام بده
برای فهرستهای بلند از SelectGroup و SelectLabel استفاده کنید تا گزینهها زیر عنوان دستهشان مرتب دیده شوند، درست مثل نمونهٔ «استان تهران» و «استان فارس».
انجام نده
دهها گزینه از دستههای مختلف را در یک فهرست تخت و بیعنوان نریزید؛ کاربر باید کل لیست را بخواند تا شهر موردنظرش را پیدا کند.