انتخابگر (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) |
|---|---|---|---|
value | string | undefined | مقدار انتخاب شده (کنترلشده) |
defaultValue | string | undefined | مقدار پیشفرض (غیرکنترلشده) |
onValueChange | (value: string) => void | undefined | تابع فراخوانی هنگام تغییر مقدار |
disabled | boolean | false | غیرفعال کردن انتخابگر |
name | string | undefined | نام فیلد برای ارسال فرم |
required | boolean | false | الزامی بودن فیلد |
dir | "ltr" | "rtl" | "rtl" | جهت متن |
SelectTrigger
دکمه باز کردن منوی انتخاب
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
className | string | undefined | کلاسهای CSS سفارشی |
aria-invalid | boolean | false | نشان دادن حالت نامعتبر |
SelectContent
محتوای منوی انتخاب
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
position | "item-aligned" | "popper" | "popper" | نحوه قرارگیری محتوا نسبت به trigger |
className | string | undefined | کلاسهای CSS سفارشی |
sideOffset | number | 4 | فاصله از trigger (پیکسل) |
SelectItem
آیتم قابل انتخاب
| پراپ (Prop) | نوع (Type) | پیشفرض (Default) | توضیحات (Description) |
|---|---|---|---|
value | string | - | مقدار آیتم (الزامی) |
disabled | boolean | false | غیرفعال کردن آیتم |
className | string | undefined | کلاسهای 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