قائمة منسدلة بالبحث (Combobox)

يتيح لك مكوّن قائمة منسدلة بالبحث (Combobox) البحث في الخيارات، واختيار عدة خيارات، وإنشاء خيار جديد.

التثبيت

bash

npx @smicolon/fasla-ui@latest add combobox

قبل إضافة أي مكوّن، شغّل الأمر init مرة واحدة في مشروعك. التفاصيل في صفحة التثبيت.

معاينة

مع البحث

اختيار متعدد

إنشاء خيار جديد

الحالات

الخصائص (props)

الخاصية	النوع	الافتراضي	الوصف
`options`	`ComboboxOption[]`	لا يوجد	الخيارات المتاحة للاختيار.
`value`	`string \| string[]`	لا يوجد	القيمة المحددة، أو القيم مع `multiple`.
`onChange`	`(value) => void`	لا يوجد	تُستدعى عند تغيير الاختيار.
`placeholder`	`string`	`"Select option..."`	نص يظهر قبل الاختيار.
`searchPlaceholder`	`string`	`"Search..."`	نص يظهر في حقل البحث.
`multiple`	`boolean`	`false`	يسمح باختيار عدة خيارات.
`creatable`	`boolean`	`false`	يتيح إضافة خيار جديد.
`onCreate`	`(value) => void`	لا يوجد	تُستدعى بنص الخيار الجديد.
`emptyText`	`string`	`"No options found."`	نص يظهر حين لا تطابق النتائج.
`createText`	`string`	`"Create"`	تسمية خيار الإضافة.
`loading`	`boolean`	`false`	يعرض حالة التحميل.
`loadingText`	`string`	`"Loading..."`	نص يظهر أثناء التحميل.
`openLabel`	`string`	`"Open"`	اسم زر الفتح لقارئ الشاشة.
`closeLabel`	`string`	`"Close"`	اسم زر الإغلاق لقارئ الشاشة.
`removeLabel`	`(label) => string`	لا يوجد	اسم زر إزالة الخيار المحدد.
`disabled`	`boolean`	`false`	يعطّل القائمة ويُظهرها باهتة.
`className`	`string`	لا يوجد	أصناف (class) إضافية للمكوّن.

الاستخدام

قائمة منسدلة بالبحث بسيطة

tsx

"use client"

import { useState } from "react"
import { Combobox } from "@/components/ui/combobox"

const countries = [
  { value: "sa", label: "السعودية" },
  { value: "ae", label: "الإمارات" },
  { value: "eg", label: "مصر" },
]

export function CountryCombobox() {
  const [country, setCountry] = useState("")

  return (
    <Combobox
      options={countries}
      value={country}
      onChange={(value) => setCountry(value as string)}
      placeholder="اختر خيارًا…"
      searchPlaceholder="ابحث…"
      emptyText="لا توجد دولة مطابقة."
    />
  )
}

التحكّم بالقيمة مع البحث

tsx

"use client"

import { useState } from "react"
import { Combobox } from "@/components/ui/combobox"

const countries = [
  { value: "sa", label: "السعودية" },
  { value: "ae", label: "الإمارات" },
  { value: "eg", label: "مصر" },
]

export function ControlledCountryCombobox() {
  const [country, setCountry] = useState("sa")

  return (
    <Combobox
      options={countries}
      value={country}
      onChange={(value) => setCountry(value as string)}
      placeholder="اختر خيارًا…"
      searchPlaceholder="ابحث…"
      emptyText="لا توجد دولة مطابقة."
    />
  )
}

اختيار متعدد

tsx

"use client"

import { useState } from "react"
import { Combobox } from "@/components/ui/combobox"

const countries = [
  { value: "sa", label: "السعودية" },
  { value: "ae", label: "الإمارات" },
  { value: "eg", label: "مصر" },
]

export function CountriesCombobox() {
  const [selected, setSelected] = useState<string[]>([])

  return (
    <Combobox
      options={countries}
      multiple
      value={selected}
      onChange={(value) => setSelected(value as string[])}
      placeholder="اختر خيارًا…"
      searchPlaceholder="ابحث…"
      emptyText="لا توجد دولة مطابقة."
    />
  )
}

إنشاء خيار جديد

tsx

"use client"

import { useState } from "react"
import { Combobox } from "@/components/ui/combobox"

export function CreatableCountryCombobox() {
  const [countries, setCountries] = useState([
    { value: "sa", label: "السعودية" },
    { value: "ae", label: "الإمارات" },
    { value: "eg", label: "مصر" },
  ])
  const [country, setCountry] = useState("")

  return (
    <Combobox
      options={countries}
      value={country}
      onChange={(value) => setCountry(value as string)}
      creatable
      // أضف الخيار الجديد إلى قائمتك
      onCreate={(label) => {
        setCountries((current) => [...current, { value: label, label }])
        setCountry(label)
      }}
      placeholder="اختر خيارًا…"
      searchPlaceholder="ابحث…"
      emptyText="لا توجد دولة مطابقة."
      createText="إضافة"
    />
  )
}