انتقل إلى المحتوى
TopClass UI

قائمة اختيار مع بحث

حقل نص يصفّي قائمة أثناء الكتابة. يعرض الصفوف الظاهرة فقط بعد 200 خيار، ويستدعي loadMore لجلب الصفحة التالية.

client - الحجم لم يُقَس بعد

قائمة اختيار مع بحث

client - الحجم لم يُقَس بعد

حقل نص يصفّي قائمة أثناء الكتابة. يعرض الصفوف الظاهرة فقط بعد 200 خيار، ويستدعي loadMore لجلب الصفحة التالية.

تثبيت

جرّبه

size
invalid
fullWidth
placement
visibleRows
hasMore
loadMoreThreshold
status

الشيفرة

combobox.tsx
import { Combobox } from 'topclassui/combobox'

<div className="grid justify-items-start gap-1">
  <label htmlFor="combobox-playground" className="text-sm font-medium text-body">Framework</label>
  <Combobox id="combobox-playground" items={FRAMEWORKS} placeholder="Search frameworks" />
</div>

تجري التصفية على الخيارات المحمّلة حتى الآن؛ وتصل الصفحة التالية عبر hasMore وloadMore.

كل الحالات، بدون تمرير الفأرة

4 حالات

أو استورده من الحزمة

topclassui/combobox
import { Combobox } from 'topclassui/combobox'

ثبّت مرة واحدة:npm i topclassui@beta zod

أمثلة

  • items يأخذ { value, label, disabled? }: تُطابق الكتابة مع التسمية، ويستلم النموذج القيمة. أبقِ المصفوفة نفسها بين مرات العرض.
  • المكوّن يطلب ولا يجلب أبدًا: مع hasMore يستدعي loadMore حين تقترب القائمة المفتوحة من نهايتها بمقدار loadMoreThreshold صفوف (10)، وأنت تضيف الصفحة التالية إلى items.
  • status يخبر بما هو قادم: loading يرسم مؤشر تحميل مكان السهم، وloading-more يكتب سطرًا تحت الخيارات.
  • virtualize قيمته auto افتراضيًا: بعد 200 خيار تُركَّب الصفوف الظاهرة وقليل حولها فقط، ويبقى التمييز قادرًا على الوصول إلى كل خيار.
  • البحث بلا نتيجة يعرض emptyFallback، أو تسمية "لا نتائج" من المزوّد. وmaxLength يحدّ البحث بـ256 حرفًا افتراضيًا.
basic
form
sizes
load-more

Pages asked for: 0, loaded: 1

status
ten-thousand
long-content
بالعربية، من اليمين إلى اليسار

الخصائص

خصائص Combobox
الخاصيةالنوعالافتراضيالحدودالوصف
items*readonly ListOption[]--The options, as plain data a Server Component can pass. Keep the array stable between renders.
aria-labelstring--The name read out when no visible label names the control.
aria-labelledbystring--The id of the visible text that names the control.
idstring--The id a <label htmlFor> points at.
classNamestring--On the input, merged last.
containerBase.Portal.Props['container']--Where the list mounts; the body when left out.
defaultValuestring | null--The value the page opens on, and the one a form reset returns to.
emptyFallbackReactNode--What an empty list says, in place of labels.collection.noResults.
fullWidthbooleanfalse-Fills its parent instead of taking the width of an Input.
hasMorebooleanfalse-More pages exist, so loadMore is called when the open list nears its end.
invalidbooleanfalse-Marks the value as wrong: sets aria-invalid on the input, whose line turns to danger and thickens.
keepMountedBase.Portal.Props['keepMounted']--Keeps the list mounted while it is closed.
loadMore(() => void | Promise<void>)--Called with no argument when the list nears its end while hasMore is set, never while closed. Client-only, or a Server Action.
loadMoreThresholdinteger, min 0, max 20010min 0, max 200How many rows from the end loadMore is called, clamped.
maxLengthunknown256-The cap on the typed query, 256 by default; null removes it. No counter is drawn.
onValueChange((value: string | null, details: ComboboxChan...--Called with the value of the chosen option, or null when the choice is cleared. Client-only.
placementtop | top-start | top-end | bottom | bottom-start | bottom-end | start | start-top | start-bottom | end | end-top | end-bottom"bottom-start"-The side and alignment the list opens at; start and end mirror in Arabic.
refRef<HTMLInputElement>--The visible input.
sizexs | sm | md | lg | xl | custom"md"-The height, padding and type step of the input; custom emits no size classes.
statusidle | loading | loading-more"idle"-loading draws a spinner and, with no options, says so; loading-more says so under the list.
valuestring | null--The chosen option's value, or null for none. Use with onValueChange when controlled.
virtualizeunknown"auto"-auto windows the list above 200 options; true always, false never.
visibleRowsinteger, min 1, max 207min 1, max 20Rows the list shows before it scrolls, clamped. Left out, the --tc-list-rows knob applies.

لوحة المفاتيح وإمكانية الوصول

لوحة مفاتيح Combobox
المفاتيحما يفعله
ArrowDownيفتح القائمة على صفها الأول؛ وداخلها ينتقل إلى الأسفل ويعود إلى الحقل بعد الصف الأخير.
ArrowUpينتقل إلى الأعلى؛ وبعد الصف الأول يعود إلى الحقل، ثم إلى الصف الأخير.
Enterيختار الخيار المميّز ويغلق القائمة.
Escapeيغلق القائمة؛ وعلى الحقل المغلق يمسح القيمة.
ArrowLeftArrowRightيحرّكان المؤشر داخل النص.
HomeEndينقلان المؤشر إلى بداية النص أو نهايته.
  • الاسم مطلوب: id لتسمية <label htmlFor>، أو aria-label، أو aria-labelledby. الحقل هو <input role="combobox">.
  • يبقى التركيز في الحقل بينما يتحرك التمييز في القائمة، كما في نمط القائمة القابلة للكتابة من ARIA Authoring Practices.
  • مفتاح Escape على الحقل المغلق يمسح القيمة، فيرسل النموذج بعدها قيمة فارغة.

من اليمين إلى اليسار

يقع السهم وعلامة الاختيار على اليسار، وbottom-start تحاذي القائمة مع الحافة اليمنى للحقل. ArrowLeft وArrowRight يحرّكان المؤشر داخل النص، في العربية أيضًا.

الخادم والمتصفح

مكوّن متصفح: يُعرض على الخادم ثم يُرطَّب في المتصفح.

الملفات: index.tsx, client.tsx.

على الشارة: client - الحجم لم يُقَس بعد.