کمبوباکس (Combobox)

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

نصب (Installation)

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

نمونه‌ها (Examples)

نمونه پایه (Basic)

کمبوباکس ساده با لیست فریم‌ورک‌ها.

مشاهده کد

1import {
2  Combobox,
3  ComboboxTrigger,
4  ComboboxPopover,
5  ComboboxOption,
6  ComboboxNoOptions,
7} from "@/components/ui/combobox";
8
9const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"] as const;
10
11export default function BasicComboboxExample() {
12  return (
13    <Combobox items={frameworks}>
14      <ComboboxTrigger className="w-full max-w-xs" />
15      <ComboboxPopover>
16        <ComboboxNoOptions>موردی یافت نشد.</ComboboxNoOptions>
17        <ComboboxOption id="frameworks" />
18      </ComboboxPopover>
19    </Combobox>
20  );
21}
22

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

مدیریت مقدار انتخاب شده با استفاده از state خارجی.

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

مشاهده کد

1"use client";
2
3import * as React from "react";
4import {
5  Combobox,
6  ComboboxTrigger,
7  ComboboxPopover,
8  ComboboxOption,
9  ComboboxNoOptions,
10} from "@/components/ui/combobox";
11
12const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"] as const;
13
14export default function ControlledComboboxExample() {
15  const [value, setValue] = React.useState<string | null>(null);
16
17  return (
18    <div className="flex flex-col gap-3">
19      <Combobox
20        items={frameworks}
21        value={value}
22        onValueChange={setValue}
23      >
24        <ComboboxTrigger className="w-full max-w-xs" />
25        <ComboboxPopover>
26          <ComboboxNoOptions>موردی یافت نشد.</ComboboxNoOptions>
27          <ComboboxOption id="frameworks" />
28        </ComboboxPopover>
29      </Combobox>
30      <p className="text-sm text-muted-foreground">
31        مقدار انتخاب شده: {value ?? "هیچ"}
32      </p>
33    </div>
34  );
35}
36

آیتم‌های سفارشی (Custom Items)

پر کردن کمبوباکس با آبجکت‌های سفارشی و استفاده از itemToStringValue.

مشاهده کد

1import {
2  Combobox,
3  ComboboxTrigger,
4  ComboboxPopover,
5  ComboboxOption,
6  ComboboxNoOptions,
7} from "@/components/ui/combobox";
8
9type Framework = {
10  label: string;
11  value: string;
12};
13
14const frameworks: Framework[] = [
15  { label: "Next.js", value: "next" },
16  { label: "SvelteKit", value: "sveltekit" },
17  { label: "Nuxt", value: "nuxt" },
18];
19
20export default function CustomItemsComboboxExample() {
21  return (
22    <Combobox
23      items={frameworks}
24      itemToStringValue={(framework) => framework.label}
25    >
26      <ComboboxTrigger className="w-full max-w-xs" />
27      <ComboboxPopover>
28        <ComboboxNoOptions>موردی یافت نشد.</ComboboxNoOptions>
29        <ComboboxOption id="frameworks" />
30      </ComboboxPopover>
31    </Combobox>
32  );
33}
34

مرجع API (API Reference)

Combobox

کامپوننت ریشه کمبوباکس که منطق انتخاب و فیلتر را مدیریت می‌کند.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`items`	`T[]`	`[]`	آرایه آیتم‌هایی که در لیست پیشنهادها نمایش داده می‌شوند.
`value`	`T \| T[] \| null`	`undefined`	مقدار انتخاب شده در حالت کنترل‌شده.
`defaultValue`	`T \| T[] \| null`	`undefined`	مقدار پیش‌فرض در حالت غیرکنترل‌شده.
`onValueChange`	`(value: T \| T[] \| null) => void`	`undefined`	تابع فراخوانی هنگام تغییر مقدار انتخاب شده.
`multiple`	`boolean`	`false`	فعال کردن انتخاب چندگانه.
`itemToStringValue`	`(item: T) => string`	`undefined`	تابع تبدیل آیتم‌های سفارشی به رشته برای نمایش و فیلتر کردن (در صورت استفاده از آبجکت).

ComboboxTrigger

تریگر/اینپوت کمبوباکس که کاربر در آن تایپ می‌کند.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی برای دکمه/اینپوت کمبوباکس.
`aria-invalid`	`boolean`	`false`	نشان دادن حالت نامعتبر برای اعتبارسنجی فرم.

ComboboxOption

آیتم‌های لیست پیشنهادها.

پراپ (Prop)	نوع (Type)	پیش‌فرض (Default)	توضیحات (Description)
`className`	`string`	`-`	کلاس‌های CSS سفارشی برای آیتم‌های لیست.

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

کیبورد (Keyboard)

Arrow Down / Arrow Up — حرکت بین آیتم‌های لیست.
Enter — انتخاب آیتم هایلایت‌شده.
Escape — بستن لیست پیشنهادها بدون تغییر مقدار.
Tab — بستن لیست و حرکت به فیلد بعدی.

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

برای دسترسی‌پذیری بهتر، کمبوباکس را همراه با Field و FieldLabel استفاده کنید یا از ویژگی‌های aria-label و aria-labelledby استفاده کنید.

پشتیبانی RTL

کمبوباکس به صورت RTL-first طراحی شده است؛ متن ورودی و آیتم‌ها راست‌چین هستند و آیکون فلش در سمت چپ (برای RTL) قرار می‌گیرد.

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

استفاده به جای Select در لیست‌های بزرگ

زمانی که تعداد گزینه‌ها زیاد است (ده‌ها یا صدها مورد)، به جای Select از Combobox استفاده کنید تا کاربر بتواند با تایپ کردن سریع‌تر به گزینه مورد نظر برسد.

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

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

کار با آبجکت‌ها (Objects as Items)

برای آیتم‌های پیچیده، همیشه itemToStringValue را تنظیم کنید تا نحوه نمایش و فیلتر شدن آن‌ها مشخص و پایدار باشد.

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

1import {
2  Combobox,
3  ComboboxTrigger,
4  ComboboxPopover,
5  ComboboxOption,
6  ComboboxNoOptions,
7} from "@/components/ui/combobox";
8
9const languages = ["TypeScript", "JavaScript", "Python", "Go", "Rust"] as const;
10
11export default function ComboboxUsageExample() {
12  return (
13    <Combobox items={languages}>
14      <ComboboxTrigger className="w-full max-w-xs" />
15      <ComboboxPopover>
16        <ComboboxNoOptions>موردی یافت نشد.</ComboboxNoOptions>
17        <ComboboxOption id="languages" />
18      </ComboboxPopover>
19    </Combobox>
20  );
21}
22