Combobox

کامپوننت Combobox برای انتخاب چندتایی از میان یک لیست گزینه، همراه با جستجوی زنده، استفاده می‌شود. هر گزینه‌ی انتخاب‌شده به‌صورت یک Chip نمایش داده می‌شود و با کلیک روی × یا فشردن Backspace (وقتی جعبه‌ی جستجو خالی است) حذف می‌شود.

Import

import { Combobox } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

Combobox کاملاً controlled است — یعنی همیشه باید value و onChange را خودت مدیریت کنی:

import { useState } from "react";
import { Combobox } from "fara-ui";

function FrameworkSelector() {
  const [value, setValue] = useState<string[]>([]);
  const options = [
    { value: "react", label: "React" },
    { value: "vue", label: "Vue" },
    { value: "svelte", label: "Svelte" },
  ];

  return (
    <div>
      <Combobox
        options={options}
        value={value}
        onChange={setValue}
        placeholder="فریم‌ورک‌ها را انتخاب کنید"
      />
      <p>تعداد انتخاب‌ها: {value.length}</p>
    </div>
  );
}

مقدار value فقط شامل value گزینه‌هاست، نه label آن‌ها:

// اگر کاربر React و Vue را انتخاب کرده باشد:
["react", "vue"];

برای نمایش نام گزینه‌های انتخاب‌شده، مقدارهای value را با آرایه‌ی options تطبیق بده:

const selectedLabels = options
  .filter((option) => value.includes(option.value))
  .map((option) => option.label);

Playground

می‌توانی واقعاً گزینه‌ها را جستجو، انتخاب و حذف کنی و هم‌زمان تنظیمات را تغییر بدهی:

placeholder

disabled

<Combobox
  options={options}
  value={value}
  onChange={setValue}
  placeholder="انتخاب فریم‌ورک..."
/>

Keyboard Interaction

• Backspace روی جعبه‌ی جستجوی خالی، آخرین گزینه‌ی انتخاب‌شده را حذف می‌کند.
• Escape منوی باز را می‌بندد.
• کلیک بیرون از کامپوننت هم منو را می‌بندد.

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

Accessibility

• منوی باز با role="listbox" و هر گزینه با role="option" مشخص شده است.
• گزینه‌های از قبل انتخاب‌شده از لیست باز حذف می‌شوند (چون به‌صورت Chip در بالای جعبه نمایش داده شده‌اند)، پس هیچ ابهامی در وضعیت انتخاب پیش نمی‌آید.
• برای استفاده در صفحه‌های RTL، روی ریشه‌ی برنامه dir="rtl" قرار بده.

Data Attributes and Customize CSS

Combobox hookهای پایدار زیر را در DOM تولید می‌کند:

<div data-fara-combobox>
  <div data-fara-combobox-trigger>
    <span data-fara-combobox-chip>React</span>
    <input data-fara-combobox-search-input />
  </div>
</div>

Attribute	کاربرد
data-fara-combobox	ریشه‌ی کامپوننت
data-fara-combobox-trigger	ناحیه‌ی کلیک و نمایش انتخاب‌ها
data-fara-combobox-chip	هر گزینه‌ی انتخاب‌شده
data-fara-combobox-search-input	فیلد جستجو
data-fara-combobox-dropdown	پنل گزینه‌ها؛ در Portal قرار می‌گیرد
data-fara-combobox-option-list	لیست گزینه‌ها
data-fara-combobox-option	هر گزینه
data-fara-combobox-empty	حالت بدون نتیجه

برای تغییر layout یک نمونه‌ی خاص، از className استفاده کن:

<Combobox className="team-combobox" options={options} value={value} onChange={setValue} />

.team-combobox {
  max-width: 360px;
}

[data-fara-combobox-option] {
  padding: 10px 12px;
}

[data-fara-combobox-trigger][data-disabled] {
  opacity: 0.6;
}

dropdown در document.body و با Portal رندر می‌شود؛ بنابراین برای استایل‌دادن به پنل، selector مربوط به data-fara-combobox-dropdown را مستقل از container صفحه بنویس.

Use in Form

برای ارسال مقدارهای انتخاب‌شده، می‌توانی قبل از submit آن‌ها را در state داشته باشی:

function SkillsForm() {
  const [skills, setSkills] = useState<string[]>([]);
  const options = [
    { value: "typescript", label: "TypeScript" },
    { value: "react", label: "React" },
    { value: "css", label: "CSS" },
  ];

  function handleSubmit(event) {
    event.preventDefault();
    console.log({ skills });
  }

  return (
    <form onSubmit={handleSubmit}>
      <Combobox
        options={options}
        value={skills}
        onChange={setSkills}
        emptyMessage="مهارتی پیدا نشد"
      />
      <button type="submit">ذخیره</button>
    </form>
  );
}

SSR Note

Combobox با SSR و Next.js سازگار است؛ dropdown در رندر سرور خروجی تولید نمی‌کند و پس از hydration در مرورگر فعال می‌شود. نیازی به dynamic(..., { ssr: false }) نیست.

Props

Prop	Type	Default	Description
options	{ value: string; label: string }[]	-	(الزامی) لیست کامل گزینه‌های قابل‌انتخاب
value	string[]	-	(الزامی) آرایه‌ی مقادیر انتخاب‌شده‌ی فعلی
onChange	(value: string[]) => void	-	(الزامی) فراخوانی‌شده با آرایه‌ی جدید هنگام انتخاب یا حذف یک گزینه
placeholder	string	"انتخاب کنید..."	متن راهنما وقتی هیچ گزینه‌ای انتخاب نشده
disabled	boolean	false	غیرفعال کردن کل کامپوننت
emptyMessage	string	"نتیجه‌ای یافت نشد"	متنی که وقتی جستجو نتیجه‌ای نداشته باشد نمایش داده می‌شود
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی