Select

کامپوننت Select برای انتخاب یک گزینه از میان لیستی از گزینه‌ها استفاده می‌شود. برخلاف <select> بومی HTML، ظاهری سفارشی دارد و قابلیت جستجو در گزینه‌ها را هم به‌صورت داخلی ارائه می‌دهد.

Import

import { Select } from "fara-ui";

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

Basic Usage

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

export function CitySelector() {
  const [city, setCity] = useState("");

  return (
    <div>
      <label htmlFor="city">شهر</label>
      <Select
        options={[
          { value: "tehran", label: "تهران" },
          { value: "isfahan", label: "اصفهان" },
        ]}
        value={city}
        onChange={setCity}
        placeholder="شهر را انتخاب کنید"
      />
      <p>مقدار انتخاب‌شده: {city || "—"}</p>
    </div>
  );
}

مقدار value باید برابر با value یکی از گزینه‌ها باشد، نه label نمایشی آن.

Playground

valuetehranisfahanshiraztabriz

disabled

placeholder

<Select
  options={[...]}
  value="tehran"
  placeholder="انتخاب کنید..."
  onChange={...}
/>

Searching Options

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

Empty State

اگر هیچ گزینه‌ای با عبارت جستجو مطابقت نداشته باشد، پیام «نتیجه‌ای یافت نشد» نمایش داده می‌شود.

Use in Form

برای ارسال مقدار انتخاب‌شده، state را در فرم نگه دار:

function AddressForm() {
  const [province, setProvince] = useState("");
  const options = [
    { value: "tehran", label: "تهران" },
    { value: "fars", label: "فارس" },
    { value: "gilan", label: "گیلان" },
  ];

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

  return (
    <form onSubmit={handleSubmit}>
      <Select
        options={options}
        value={province}
        onChange={setProvince}
        placeholder="استان را انتخاب کنید"
      />
      <button type="submit" disabled={!province}>
        ثبت
      </button>
    </form>
  );
}

Accessing the Input with ref

ref به input داخلی داده می‌شود و برای focus کردن یا خواندن مقدار DOM کاربرد دارد:

import { useRef } from "react";

function FocusableSelect() {
  const inputRef = useRef(null);

  return (
    <>
      <Select
        ref={inputRef}
        options={[{ value: "one", label: "گزینه اول" }]}
        placeholder="انتخاب کنید"
      />
      <button type="button" onClick={() => inputRef.current?.focus()}>
        فوکوس روی انتخاب‌گر
      </button>
    </>
  );
}

Data Attributes and Customize CSS

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

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

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

<Select className="city-select" options={options} value={city} onChange={setCity} />

.city-select {
  max-width: 320px;
}

[data-fara-select-option][data-selected] {
  font-weight: 700;
}

[data-fara-select-empty] {
  color: #64748b;
}

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

Accessibility and SSR

• برای هر Select یک label مرتبط با input در نظر بگیر؛ placeholder جایگزین label نیست.
• برای حالت خطا یا توضیح اضافی، از aria-describedby روی input استفاده کن.
• Select با SSR و Next.js سازگار است؛ dropdown در رندر سرور خروجی تولید نمی‌کند و پس از hydration در مرورگر فعال می‌شود. نیازی به dynamic(..., { ssr: false }) نیست.

Props

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

interface SelectOption {
  value: string;
  label: string;
}