انتخاب چندتایی (MultiSelect)

معرفی

کامپوننت MultiSelect برای انتخاب چندین گزینه از لیست استفاده می‌شود. مقادیر انتخاب‌شده به صورت FilterChip نمایش داده می‌شوند.

چه زمانی استفاده کنیم:

• وقتی کاربر باید چندین گزینه از لیست مشخصی انتخاب کند
• وقتی گزینه‌های انتخاب‌شده باید به صورت chip قابل حذف نمایش داده شوند
• برای فیلترهای چند مقداری در فرم‌ها و داشبوردها

چه زمانی استفاده نکنیم:

• برای انتخاب تک گزینه — از Select استفاده کنید
• برای بیش از ۱۰۰ گزینه — از Command با multi-select استفاده کنید
• وقتی گزینه‌ها باید همیشه دیده شوند — از Checkbox group استفاده کنید

زمین بازی

با تغییر تنظیمات زیر، چندانتخابی را به‌صورت زنده مشاهده کنید.

استفاده

import { MultiSelect } from '@parto-system-design/ui'

const options = [
  { value: 'tehran', label: 'تهران' },
  { value: 'isfahan', label: 'اصفهان' },
  { value: 'shiraz', label: 'شیراز' },
  { value: 'tabriz', label: 'تبریز' },
]

const [selected, setSelected] = useState<string[]>([])

;<MultiSelect options={options} value={selected} onValueChange={setSelected} placeholder="شهر را انتخاب کنید" />

با محدودیت انتخاب

<MultiSelect
  options={options}
  value={selected}
  onValueChange={setSelected}
  maxSelected={3}
  placeholder="حداکثر ۳ مورد"
/>

حالت بارگذاری

<MultiSelect options={[]} isLoading={true} placeholder="در حال بارگذاری..." />

Props

حالت‌ها و انواع

پایه — انتخاب چندتایی با چیپ

ساده‌ترین استفاده؛ بدون محدودیت تعداد. هر گزینه‌ی انتخاب‌شده به‌صورت FilterChip در trigger ظاهر می‌شود.

const options = [
  { value: 'tehran', label: 'تهران' },
  { value: 'isfahan', label: 'اصفهان' },
  { value: 'shiraz', label: 'شیراز' },
]

<MultiSelect
  options={options}
  value={selected}
  onValueChange={setSelected}
  placeholder="شهر را انتخاب کنید"
/>

maxSelected — سقف تعداد انتخاب

با maxSelected بعد از رسیدن به سقف، انتخاب گزینه‌های جدید نادیده گرفته می‌شود. مناسب برای فیلترهایی که منطقاً تعداد محدود دارند.

<MultiSelect
  options={options}
  value={selected}
  onValueChange={setSelected}
  maxSelected={3}
  placeholder="حداکثر ۳ مورد"
/>

maxDisplayed — جمع‌بندی چیپ‌ها به «+N»

وقتی تعداد انتخاب‌ها زیاد است، فقط maxDisplayed چیپ اول نمایش داده می‌شود و باقی به‌صورت یک Badge شمارنده جمع می‌شوند تا فضا اشغال نشود.

<MultiSelect options={longOptionsList} value={selected} onValueChange={setSelected} maxDisplayed={2} />

حالت بارگذاری — Skeleton در dropdown

وقتی گزینه‌ها از API می‌آیند، تا قبل از resolve با isLoading={true} Skeleton در dropdown نمایش دهید.

<MultiSelect options={[]} isLoading={true} placeholder="در حال بارگذاری..." />

حالت غیرفعال

با disabled={true} کل کنترل (trigger و dropdown) غیرفعال می‌شود؛ مناسب برای فرم‌های read-only.

<MultiSelect options={options} value={['tehran']} disabled={true} />

گزینه‌های دامنه — شدت/پلتفرم

برای فیلترهای افکارسنجی می‌توانید مقادیر value را به کلیدهای دامنه (severity، platform) map کنید و در parent به توکن رنگی تبدیل کنید.

const severityOptions = [
  { value: 'urgent', label: 'فوری' },
  { value: 'high', label: 'بالا' },
  { value: 'medium', label: 'متوسط' },
  { value: 'low', label: 'پایین' },
]

<MultiSelect
  options={severityOptions}
  value={selectedSeverity}
  onValueChange={setSelectedSeverity}
  placeholder="شدت را انتخاب کنید"
/>

راهنمای استفاده

دسترسی‌پذیری

• باز و بسته کردن dropdown با Enter و Space
• پیمایش بین گزینه‌ها با ↑ و ↓
• جستجوی درون لیست با تایپ کردن
• حذف چیپ‌ها با کلیک روی دکمه حذف
• پشتیبانی کامل از RTL

کامپوننت‌های مرتبط

• اگر فقط نیاز به انتخاب یک گزینه دارید → Select
• اگر لیست گزینه‌ها بسیار بزرگ است و نیاز به جستجوی پیشرفته دارید → Command
• اگر نیاز به نمایش فیلترهای فعال به صورت chip دارید → FilterChip
• اگر نیاز به جستجو و انتخاب از API دارید → Autocomplete