انتخابگر (Select)

کامپوننت انتخاب گزینه از لیست

معرفی

کامپوننت Select برای انتخاب یک گزینه از لیست کشویی استفاده می‌شود.

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

  • برای بیش از 15 گزینه — از Autocomplete استفاده کنید
  • برای انتخاب چند گزینه — از MultiSelect استفاده کنید
  • برای 2-5 گزینه که باید همیشه نمایش داده شوند — از RadioGroup استفاده کنید

استفاده

import { Select, SelectTrigger, SelectValue, SelectContent, SelectItem } from '@partodata/ui'
;<Select defaultValue="option1">
  <SelectTrigger className="w-[220px]">
    <SelectValue placeholder="انتخاب کنید" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">گزینه 1</SelectItem>
    <SelectItem value="option2">گزینه 2</SelectItem>
    <SelectItem value="option3">گزینه 3</SelectItem>
  </SelectContent>
</Select>

زمین بازی

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

زمین بازی
تنظیمات
ظاهر
حالت
محتوا
کد این نمونه به‌صورت خودکار قابل تولید نیست — برای کد آماده‌ی copy/paste به بخش «استفاده» در بالای صفحه مراجعه کنید.

اندازه‌ها

کامپوننت SelectTrigger از پنج اندازهٔ نردبان کنترل‌ها پشتیبانی می‌کند. پیش‌فرض md (38 پیکسل) است، اندازهٔ فیلد فرم؛ در نوار ابزار، FilterBar و سرِ کارت‌ها و سربرگ‌ها ردیف آن را sm (30 پیکسل) می‌کند:

<div className="flex flex-col gap-4">
  <Select>
    <SelectTrigger size="xs" className="w-[180px]">
      <SelectValue placeholder="خیلی کوچک (xs)" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه 1</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="sm" className="w-[180px]">
      <SelectValue placeholder="کوچک (sm) — نوار ابزار" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه 1</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="md" className="w-[180px]">
      <SelectValue placeholder="متوسط (md) — پیش‌فرض" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه 1</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="lg" className="w-[180px]">
      <SelectValue placeholder="بزرگ (lg)" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه 1</SelectItem>
    </SelectContent>
  </Select>

  <Select>
    <SelectTrigger size="xl" className="w-[180px]">
      <SelectValue placeholder="خیلی بزرگ (xl)" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="1">گزینه 1</SelectItem>
    </SelectContent>
  </Select>
</div>

با Label

<div className="space-y-2">
  <label htmlFor="framework">فریمورک</label>
  <Select>
    <SelectTrigger id="framework" className="w-[180px]">
      <SelectValue placeholder="انتخاب فریمورک" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="next">Next.js</SelectItem>
      <SelectItem value="react">React</SelectItem>
      <SelectItem value="vue">Vue</SelectItem>
      <SelectItem value="svelte">Svelte</SelectItem>
    </SelectContent>
  </Select>
</div>

کنترل شده

const [value, setValue] = React.useState('')

;<Select value={value} onValueChange={setValue}>
  <SelectTrigger>
    <SelectValue placeholder="انتخاب کنید" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="apple">سیب</SelectItem>
    <SelectItem value="banana">موز</SelectItem>
    <SelectItem value="orange">پرتقال</SelectItem>
  </SelectContent>
</Select>

با گروه‌بندی

import { SelectGroup, SelectLabel } from '@partodata/ui'
;<Select>
  <SelectTrigger className="w-[280px]">
    <SelectValue placeholder="انتخاب میوه" />
  </SelectTrigger>
  <SelectContent>
    <SelectGroup>
      <SelectLabel>میوه‌های استوایی</SelectLabel>
      <SelectItem value="banana">موز</SelectItem>
      <SelectItem value="pineapple">آناناس</SelectItem>
      <SelectItem value="mango">انبه</SelectItem>
    </SelectGroup>
    <SelectGroup>
      <SelectLabel>میوه‌های معمولی</SelectLabel>
      <SelectItem value="apple">سیب</SelectItem>
      <SelectItem value="orange">پرتقال</SelectItem>
      <SelectItem value="grape">انگور</SelectItem>
    </SelectGroup>
  </SelectContent>
</Select>

غیرفعال کردن گزینه

<Select>
  <SelectTrigger>
    <SelectValue placeholder="انتخاب کنید" />
  </SelectTrigger>
  <SelectContent>
    <SelectItem value="option1">گزینه 1</SelectItem>
    <SelectItem value="option2" disabled>
      گزینه 2 (غیرفعال)
    </SelectItem>
    <SelectItem value="option3">گزینه 3</SelectItem>
  </SelectContent>
</Select>

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

Select از اجزای زیر تشکیل شده است:

  • Select: کانتینر اصلی و مدیریت state
  • SelectTrigger: دکمه باز کننده منو
  • SelectValue: نمایش مقدار انتخاب شده
  • SelectContent: کانتینر محتوای منو
  • SelectItem: هر گزینه
  • SelectGroup: گروه‌بندی گزینه‌ها
  • SelectLabel: برچسب گروه
  • SelectSeparator: خط جداکننده بین گزینه‌ها

Props

Select

Prop

Type

SelectTrigger

Prop

Type

SelectSeparator

Prop

Type

SelectItem

Prop

Type

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

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

  • از Select برای انتخاب از فهرست‌های ثابت و مشخص استفاده کنید - از Autocomplete برای جستجوی پویا یا فهرست‌های بلند استفاده کنید - همیشه یک مقدار placeholder مناسب تعریف کنید

از این‌ها پرهیز کنید

  • از Select برای فهرست‌های بیش از 20 گزینه استفاده نکنید — به‌جای آن از Autocomplete استفاده کنید - از تغییر مستقیم مقدار انتخاب‌شده بدون تعامل کاربر خودداری کنید - گزینه‌های Select را خیلی طولانی نکنید — حداکثر 50 کاراکتر

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

  • پیمایش با کیبورد (Arrow keys، Enter، Space)
  • جستجو با تایپ
  • از role="combobox" استفاده می‌شود
  • aria-expanded برای وضعیت باز/بسته
  • aria-selected برای گزینه انتخاب شده
  • پشتیبانی کامل از screen readers

ملاحظات RTL

  • منوی dropdown به‌درستی راست‌چین می‌شود
  • آیکون کشویی در سمت مناسب قرار می‌گیرد
  • متن‌ها راست‌چین هستند
  • پیمایش کیبورد با RTL سازگار است
  • نشانگر انتخاب در سمت راست نمایش داده می‌شود

تعامل با کیبورد

  • Enter یا Space: باز/بسته کردن لیست - Arrow Down / Arrow Up: حرکت بین گزینه‌ها - Escape: بستن لیست - حروف: جستجوی سریع گزینه‌ها

مرتبط

  • Autocomplete — Select با قابلیت جستجو برای لیست‌های بزرگ
  • Multi Select — انتخاب چند گزینه همزمان
  • Radio Group — برای انتخاب از بین 2-5 گزینه قابل مشاهده
  • Input — برای ورودی آزاد به‌جای انتخاب از لیست

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

  • Autocomplete — برای لیست‌های بزرگ با جستجو
  • MultiSelect — برای انتخاب چند گزینه
  • RadioGroup — برای گزینه‌های کم و قابل رویت
  • NativeSelect — برای فرم‌های ساده بدون styling پیچیده