انتخابگر (Select)

نمایش لیست گزینه‌ها برای انتخاب کاربر با پشتیبانی کامل از RTL و دسترسی‌پذیری

نصب (Installation)

1npx @quark-lab/rad-ui add select

نمونه‌ها (Examples)

استفاده پایه (Basic Usage)

ساده‌ترین حالت استفاده از انتخابگر با لیست میوه‌ها

مشاهده کد
1import {
2  Select,
3  SelectContent,
4  SelectGroup,
5  SelectItem,
6  SelectLabel,
7  SelectTrigger,
8  SelectValue,
9} from "@/components/ui/select";
10
11export default function BasicExample() {
12  return (
13    <Select>
14      <SelectTrigger className="w-full max-w-48">
15        <SelectValue placeholder="یک میوه انتخاب کنید" />
16      </SelectTrigger>
17      <SelectContent>
18        <SelectGroup>
19          <SelectLabel>میوه‌ها</SelectLabel>
20          <SelectItem value="apple">سیب</SelectItem>
21          <SelectItem value="banana">موز</SelectItem>
22          <SelectItem value="blueberry">زغال‌اخته</SelectItem>
23          <SelectItem value="grapes">انگور</SelectItem>
24          <SelectItem value="pineapple">آناناس</SelectItem>
25        </SelectGroup>
26      </SelectContent>
27    </Select>
28  );
29}
30

گروه‌بندی (Groups)

استفاده از SelectGroup و SelectLabel برای سازماندهی آیتم‌ها

مشاهده کد
1import {
2  Select,
3  SelectContent,
4  SelectGroup,
5  SelectItem,
6  SelectLabel,
7  SelectSeparator,
8  SelectTrigger,
9  SelectValue,
10} from "@/components/ui/select";
11
12export default function GroupsExample() {
13  return (
14    <Select>
15      <SelectTrigger className="w-full max-w-48">
16        <SelectValue placeholder="یک مورد انتخاب کنید" />
17      </SelectTrigger>
18      <SelectContent>
19        <SelectGroup>
20          <SelectLabel>میوه‌ها</SelectLabel>
21          <SelectItem value="apple">سیب</SelectItem>
22          <SelectItem value="banana">موز</SelectItem>
23          <SelectItem value="blueberry">زغال‌اخته</SelectItem>
24        </SelectGroup>
25        <SelectSeparator />
26        <SelectGroup>
27          <SelectLabel>سبزیجات</SelectLabel>
28          <SelectItem value="carrot">هویج</SelectItem>
29          <SelectItem value="broccoli">کلم بروکلی</SelectItem>
30          <SelectItem value="spinach">اسفناج</SelectItem>
31        </SelectGroup>
32      </SelectContent>
33    </Select>
34  );
35}
36

قابل اسکرول (Scrollable)

انتخابگر با آیتم‌های زیاد که قابل اسکرول است

مشاهده کد
1import {
2  Select,
3  SelectContent,
4  SelectGroup,
5  SelectItem,
6  SelectLabel,
7  SelectTrigger,
8  SelectValue,
9} from "@/components/ui/select";
10
11export default function ScrollableExample() {
12  return (
13    <Select>
14      <SelectTrigger className="w-full max-w-64">
15        <SelectValue placeholder="یک منطقه زمانی انتخاب کنید" />
16      </SelectTrigger>
17      <SelectContent>
18        <SelectGroup>
19          <SelectLabel>آمریکای شمالی</SelectLabel>
20          <SelectItem value="est">وقت استاندارد شرقی</SelectItem>
21          <SelectItem value="cst">وقت استاندارد مرکزی</SelectItem>
22          <SelectItem value="mst">وقت استاندارد کوهستانی</SelectItem>
23          <SelectItem value="pst">وقت استاندارد اقیانوس آرام</SelectItem>
24          <SelectItem value="akst">وقت استاندارد آلاسکا</SelectItem>
25          <SelectItem value="hst">وقت استاندارد هاوایی</SelectItem>
26        </SelectGroup>
27        <SelectGroup>
28          <SelectLabel>اروپا و آفریقا</SelectLabel>
29          <SelectItem value="gmt">وقت گرینویچ</SelectItem>
30          <SelectItem value="cet">وقت اروپای مرکزی</SelectItem>
31          <SelectItem value="eet">وقت اروپای شرقی</SelectItem>
32          <SelectItem value="west">وقت تابستانی اروپای غربی</SelectItem>
33          <SelectItem value="cat">وقت آفریقای مرکزی</SelectItem>
34          <SelectItem value="eat">وقت آفریقای شرقی</SelectItem>
35        </SelectGroup>
36        <SelectGroup>
37          <SelectLabel>آسیا</SelectLabel>
38          <SelectItem value="msk">وقت مسکو</SelectItem>
39          <SelectItem value="ist">وقت استاندارد هند</SelectItem>
40          <SelectItem value="cst_china">وقت استاندارد چین</SelectItem>
41          <SelectItem value="jst">وقت استاندارد ژاپن</SelectItem>
42          <SelectItem value="kst">وقت استاندارد کره</SelectItem>
43          <SelectItem value="ist_indonesia">وقت استاندارد مرکزی اندونزی</SelectItem>
44        </SelectGroup>
45        <SelectGroup>
46          <SelectLabel>استرالیا و اقیانوسیه</SelectLabel>
47          <SelectItem value="awst">وقت استاندارد غربی استرالیا</SelectItem>
48          <SelectItem value="acst">وقت استاندارد مرکزی استرالیا</SelectItem>
49          <SelectItem value="aest">وقت استاندارد شرقی استرالیا</SelectItem>
50          <SelectItem value="nzst">وقت استاندارد نیوزیلند</SelectItem>
51          <SelectItem value="fjt">وقت فیجی</SelectItem>
52        </SelectGroup>
53        <SelectGroup>
54          <SelectLabel>آمریکای جنوبی</SelectLabel>
55          <SelectItem value="art">وقت آرژانتین</SelectItem>
56          <SelectItem value="bot">وقت بولیوی</SelectItem>
57          <SelectItem value="brt">وقت برزیلیا</SelectItem>
58          <SelectItem value="clt">وقت استاندارد شیلی</SelectItem>
59        </SelectGroup>
60      </SelectContent>
61    </Select>
62  );
63}
64

غیرفعال (Disabled)

غیرفعال کردن کل انتخابگر یا آیتم‌های خاص

مشاهده کد
1import {
2  Select,
3  SelectContent,
4  SelectGroup,
5  SelectItem,
6  SelectTrigger,
7  SelectValue,
8} from "@/components/ui/select";
9
10export default function DisabledExample() {
11  return (
12    <Select disabled>
13      <SelectTrigger className="w-full max-w-48">
14        <SelectValue placeholder="یک میوه انتخاب کنید" />
15      </SelectTrigger>
16      <SelectContent>
17        <SelectGroup>
18          <SelectItem value="apple">سیب</SelectItem>
19          <SelectItem value="banana">موز</SelectItem>
20          <SelectItem value="blueberry">زغال‌اخته</SelectItem>
21          <SelectItem value="grapes" disabled>
22            انگور
23          </SelectItem>
24          <SelectItem value="pineapple">آناناس</SelectItem>
25        </SelectGroup>
26      </SelectContent>
27    </Select>
28  );
29}
30

نامعتبر (Invalid)

نمایش حالت خطا با استفاده از Field و aria-invalid

مشاهده کد
1import {
2  Field,
3  FieldError,
4  FieldLabel,
5  Select,
6  SelectContent,
7  SelectGroup,
8  SelectItem,
9  SelectTrigger,
10  SelectValue,
11} from "@/components/ui";
12
13export default function InvalidExample() {
14  return (
15    <Field data-invalid className="w-full max-w-48">
16      <FieldLabel>میوه</FieldLabel>
17      <Select>
18        <SelectTrigger aria-invalid>
19          <SelectValue placeholder="یک میوه انتخاب کنید" />
20        </SelectTrigger>
21        <SelectContent>
22          <SelectGroup>
23            <SelectItem value="apple">سیب</SelectItem>
24            <SelectItem value="banana">موز</SelectItem>
25            <SelectItem value="blueberry">زغال‌اخته</SelectItem>
26          </SelectGroup>
27        </SelectContent>
28      </Select>
29      <FieldError>لطفاً یک میوه انتخاب کنید.</FieldError>
30    </Field>
31  );
32}
33

مرجع API (API Reference)

Select

کامپوننت اصلی انتخابگر

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestringundefinedمقدار انتخاب شده (کنترل‌شده)
defaultValuestringundefinedمقدار پیش‌فرض (غیرکنترل‌شده)
onValueChange(value: string) => voidundefinedتابع فراخوانی هنگام تغییر مقدار
disabledbooleanfalseغیرفعال کردن انتخابگر
namestringundefinedنام فیلد برای ارسال فرم
requiredbooleanfalseالزامی بودن فیلد
dir"ltr" | "rtl""rtl"جهت متن

SelectTrigger

دکمه باز کردن منوی انتخاب

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
classNamestringundefinedکلاس‌های CSS سفارشی
aria-invalidbooleanfalseنشان دادن حالت نامعتبر

SelectContent

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

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
position"item-aligned" | "popper""popper"نحوه قرارگیری محتوا نسبت به trigger
classNamestringundefinedکلاس‌های CSS سفارشی
sideOffsetnumber4فاصله از trigger (پیکسل)

SelectItem

آیتم قابل انتخاب

پراپ (Prop)نوع (Type)پیش‌فرض (Default)توضیحات (Description)
valuestring-مقدار آیتم (الزامی)
disabledbooleanfalseغیرفعال کردن آیتم
classNamestringundefinedکلاس‌های CSS سفارشی

دسترسی‌پذیری (Accessibility)

کیبورد (Keyboard)

  • Space یا Enter - باز کردن منو یا انتخاب آیتم
  • Arrow Down - حرکت به آیتم بعدی
  • Arrow Up - حرکت به آیتم قبلی
  • Escape - بستن منو
  • Tab - بستن منو و حرکت به فیلد بعدی

فوکوس (Focus)

انتخابگر دارای حلقه فوکوس واضح است و می‌توان با کیبورد به راحتی در آیتم‌ها حرکت کرد

برچسب‌گذاری (Labeling)

همیشه از FieldLabel برای برچسب‌گذاری انتخابگر استفاده کنید تا کاربران صفحه‌خوان بتوانند هدف آن را درک کنند

بهترین شیوه‌ها (Best Practices)

انتخاب بین Select و NativeSelect

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

گروه‌بندی آیتم‌ها (Grouping)

برای لیست‌های بلند، از SelectGroup و SelectLabel برای سازماندهی آیتم‌ها استفاده کنید. این کار باعث می‌شود کاربران راحت‌تر بتوانند گزینه مورد نظر خود را پیدا کنند.

متن راهنما (Placeholder Text)

از متن راهنمای واضح و مفید استفاده کنید. به جای "انتخاب کنید" از متن‌هایی مانند "یک کشور انتخاب کنید" یا "نوع محصول را انتخاب کنید" استفاده کنید.

عرض مناسب (Width)

عرض انتخابگر را به اندازه‌ای تنظیم کنید که طولانی‌ترین گزینه به راحتی قابل مشاهده باشد. از کلاس‌های w-full یا max-w-* استفاده کنید.

اعتبارسنجی (Validation)

برای نمایش خطاهای اعتبارسنجی، از Field با data-invalid و aria-invalid استفاده کنید. همیشه پیام خطای واضح و مفید نمایش دهید.

حالت کنترل‌شده (Controlled)

برای فرم‌های پیچیده، از حالت کنترل‌شده با value و onValueChange استفاده کنید تا بتوانید مقدار انتخابگر را مدیریت کنید.

نحوه استفاده (Usage)

1import {
2  Select,
3  SelectContent,
4  SelectGroup,
5  SelectItem,
6  SelectLabel,
7  SelectTrigger,
8  SelectValue,
9} from "@/components/ui/select";
10
11export default function Example() {
12  return (
13    <Select>
14      <SelectTrigger className="w-[180px]">
15        <SelectValue placeholder="تم" />
16      </SelectTrigger>
17      <SelectContent>
18        <SelectGroup>
19          <SelectItem value="light">روشن</SelectItem>
20          <SelectItem value="dark">تاریک</SelectItem>
21          <SelectItem value="system">سیستم</SelectItem>
22        </SelectGroup>
23      </SelectContent>
24    </Select>
25  );
26}
27

مثال‌های پیشرفته (Advanced Examples)

حالت کنترل‌شده (Controlled)

کنترل مقدار انتخابگر با استفاده از state

مقدار انتخاب شده: هیچ

مشاهده کد
1"use client";
2
3import * as React from "react";
4import {
5  Select,
6  SelectContent,
7  SelectGroup,
8  SelectItem,
9  SelectTrigger,
10  SelectValue,
11} from "@/components/ui/select";
12
13export default function ControlledExample() {
14  const [value, setValue] = React.useState("");
15
16  return (
17    <div className="space-y-4">
18      <Select value={value} onValueChange={setValue}>
19        <SelectTrigger className="w-[180px]">
20          <SelectValue placeholder="تم" />
21        </SelectTrigger>
22        <SelectContent>
23          <SelectGroup>
24            <SelectItem value="light">روشن</SelectItem>
25            <SelectItem value="dark">تاریک</SelectItem>
26            <SelectItem value="system">سیستم</SelectItem>
27          </SelectGroup>
28        </SelectContent>
29      </Select>
30      <p className="text-sm text-muted-foreground">
31        مقدار انتخاب شده: {value || "هیچ"}
32      </p>
33    </div>
34  );
35}
36

با فرم (With Form)

استفاده از انتخابگر در فرم با اعتبارسنجی

مشاهده کد
1"use client";
2
3import * as React from "react";
4import {
5  Field,
6  FieldLabel,
7  FieldError,
8  Select,
9  SelectContent,
10  SelectGroup,
11  SelectItem,
12  SelectTrigger,
13  SelectValue,
14  Button,
15} from "@/components/ui";
16
17export default function FormExample() {
18  const [country, setCountry] = React.useState("");
19  const [error, setError] = React.useState("");
20
21  const handleSubmit = (e: React.FormEvent) => {
22    e.preventDefault();
23    if (!country) {
24      setError("لطفاً یک کشور انتخاب کنید");
25      return;
26    }
27    setError("");
28    console.log("کشور انتخاب شده:", country);
29  };
30
31  return (
32    <form onSubmit={handleSubmit} className="space-y-4">
33      <Field data-invalid={!!error}>
34        <FieldLabel>کشور</FieldLabel>
35        <Select value={country} onValueChange={setCountry}>
36          <SelectTrigger aria-invalid={!!error}>
37            <SelectValue placeholder="کشور خود را انتخاب کنید" />
38          </SelectTrigger>
39          <SelectContent>
40            <SelectGroup>
41              <SelectItem value="ir">ایران</SelectItem>
42              <SelectItem value="tr">ترکیه</SelectItem>
43              <SelectItem value="ae">امارات</SelectItem>
44            </SelectGroup>
45          </SelectContent>
46        </Select>
47        {error && <FieldError>{error}</FieldError>}
48      </Field>
49      <Button type="submit">ارسال</Button>
50    </form>
51  );
52}
53