نظرة عامة
يجمعDropdown بين نافذة منبثقة متموضعة وصفوف مرئية والتنقل بلوحة المفاتيح والتركيز والإغلاق. يتولى تطبيقك مسؤولية البيانات والتصفية والجلب وتقسيم الصفحات. يتولى SelectionGroup مسؤولية قيم التحديد المستقلة داخل النافذة المنبثقة. استورده من twenty-ui/components.
يقبل Dropdown.Content إزاحات رقمية أو دوال لـ sideOffset وalignOffset. تتلقى دوال الإزاحة أبعاد الارتساء والنافذة المنبثقة، والجانب، والمحاذاة. استخدمها للحفاظ على تداخل منتقي الحقول المرتكز عند تحجيم الخلية.
استخدام
اختر نوع التفاعل
عيّنtype على Dropdown.Root ليتطابق مع محتويات النافذة المنبثقة.
تتيح أدوات الانتقاء إجراءات الإنشاء ومجموعات التحديد المستقلة في الصفحة نفسها، بأي ترتيب. كل مجموعة أدوات انتقاء هي مربع قائمة، وتكشف خياراتها عن
aria-selected. تستخدم مجموعات القوائم عناصر قائمة أزرار اختيار أو مربعات اختيار محددة. تستخدم مجموعات اللوحات أزرارًا تتضمن aria-pressed. تحتفظ الأوامر بدلالات الإجراء الخاصة بوضعها. امنح كل مجموعة وSearch اسمًا قابلًا للوصول. أداة الانتقاء المخصصة هذه ليست Combobox أصلية.
يأخذ Content اسمه المتاح من Trigger، أو من SubmenuTrigger في قائمة فرعية. مرر aria-label إلى Content عندما يعرض المشغّل قيمة، مثل الخيار المحدد، أو عندما لا يكون للجذر مشغّل. تكون لـ aria-label أو aria-labelledby الصريحين، وTitle داخل Header، الأولوية على اسم المشغّل.
يبقى التحديد والنافذة المنبثقة متاحين للتركيب المباشر.
البنية
Content البوابة وموضع العنصر. استخدم width وside وalign وsideOffset وalignOffset للتحكم في الموضع، وcollisionPadding لإبقاء النافذة المنبثقة أبعد عن حواف إطار العرض قبل أن تتحرك أو تنعكس (5 بكسلات افتراضيًا). يجمع Section الصفوف ذات التباعد المشترك، ويفصل Separator بين الأقسام. يحدّ Section ذو scrollable من ارتفاعه ويتيح التمرير؛ ضمّن بداخله أقسامًا معنونة لتمريرها كقائمة واحدة. تستخدم الصفوف ListItem لمظهرها.
render ليظل المشغّل عنصرًا تفاعليًا واحدًا. يجب أن تمرر المكونات المخصصة الخصائص وref المتوفرين. يقبل ActionItem أيضًا render للروابط.
إجراءات العناصر
يقبلActionItem وOptionItem actions لعناصر التحكم اللاحقة، مثل زر تحرير علامة تبويب. استخدمها في صفحات picker وpanel فقط: قد تحتوي menu على عناصر قائمة فقط، لذا لا يمكنها احتواء عناصر تحكم أخرى. عيّن actionsVisibility="always" لإبقائها مرئية؛ والقيمة الافتراضية هي "hover". تُعرض عناصر التحكم الثانوية بجانب عنصر تحكم الصف الأساسي وتُفعّل بشكل مستقل: فهي لا تغلق النافذة المنبثقة، لذا أغلقها من معالج الإجراء عند الحاجة. تظل خاصية render والمرجع ref منطبقتين على عنصر التحكم الأساسي، لذا يمكنه أيضًا أن يعمل كمقبض سحب.
استخدم tabIndex={-1} لإجراء ثانوي يقتصر على المؤشر وله بديل منفصل باستخدام لوحة المفاتيح. تستمر التنقلات باستخدام لوحة المفاتيح في التركيز على عنصر التحكم الأساسي وتنشيطه.
الرؤوس
يرتبHeader صفًا في أعلى النافذة المنبثقة. ضع فيه Title لتسمية النافذة المنبثقة بالعنوان بدلًا من المشغّل. يغلق Close النافذة المنبثقة بالطريقة نفسها التي يفعلها الضغط خارجها. يعرض افتراضيًا زر أيقونة بعلامة X، لذا امنحه aria-label، أو مرر render والعناصر التابعة لعنصر تحكم آخر. يمكن أن توجد عناصر تحكم أخرى، مثل زر يعود إلى خطوة سابقة، في الصف نفسه. استخدم Dropdown.Back عند التنقل في سجل صفحات الجذر.
البحث والتحديد
يوفرSearch الإدخال والتنقل إلى صفوف النتائج. مرر value وonValueChange؛ واحسب النتائج المطابقة أو اجلبها في تطبيقك. اعرض Loading أثناء انتظار طلب، وEmpty عندما لا تتطابق أي نتائج. يقبل كلاهما نص الحالة الذي يوفّره المستدعي.
ضمّن الخيارات القابلة للتحديد في SelectionGroup وامنح كل خيار value ثابتًا وفريدًا ضمن المجموعة. تحتاج المجموعة غير المتحكم بها أيضًا إلى id فريد ضمن شجرة القائمة المنسدلة الخاصة بها، بما في ذلك القوائم الفرعية. تحتفظ مكونات Root المتداخلة بصورة مستقلة بمخزن التحديد الخاص بها. يستخدم التحديد الفردي سلسلة نصية أو null لعدم وجود تحديد. يستخدم التحديد المتعدد مصفوفة، بما في ذلك [] لعدم وجود تحديد.
value وonValueChange للتحديد المتحكم به. يؤدي حذف value أو تمرير undefined إلى ترك التحديد غير متحكم به؛ وتعيّن defaultValue قيمته الأولية. تكون القيمة الافتراضية للمجموعة غير المتحكم بها هي null، أو [] مع multiple. يحافظ id الثابت الخاص بها على التحديد عبر الإغلاق وإعادة الفتح وعبر التنقل بين الصفحات. لا تؤدي إزالة خيار أو تصفيته إلى مسح معرّفه المحدد أو إصدار تغيير؛ ويُحدَّد الخيار مجددًا عند عودته. استخدم قيمة متحكمًا بها عندما يحتاج التطبيق إلى مسح الخيارات غير المتاحة.
تتغير كل مجموعة بصورة مستقلة. يلتزم الخيار بأقرب مجموعة له، بينما توفر الصفحة النشطة مجموعة واحدة مرتبة للتنقل بالأسهم عبر المجموعات وصفوف الإجراءات. يحافظ التنشيط المتكرر لخيار فردي محدد على قيمته دون استدعاء رد نداء تغيير آخر. يبدّل التنشيط المتعدد الخيار في المصفوفة.
يُغلق التحديد الفردي افتراضيًا؛ بينما يبقى التحديد المتعدد مفتوحًا. يغيّر SelectionGroup.closeOnSelect القيمة الافتراضية للمجموعة، ويتجاوزها OptionItem.closeOnSelect لخيار واحد. تستخدم صفوف الإجراءات closeOnClick بصورة مستقلة. يحافظ التغيير الملغى على التحديد السابق ولا يغلق النافذة المنبثقة تلقائيًا.
يتلقى onValueChange القيمة التالية وتفاصيل الحدث التي تتضمن event وreason وtrigger وcancel() وisCanceled. السبب هو item-press، وevent هو حدث التنشيط الأصلي. يتلقى OptionItem.onSelect التفاصيل نفسها قبل أن يلتزم مالكه. استدعِ cancel() في أي من ردّي النداء لمنع التحديد والإغلاق التلقائي.
Search ووجود استعلام غير فارغ، يتم تمييز أول OptionItem مؤهل عبر مجموعات الاختيار، ويقوم مفتاح Enter بتنشيطه. لا يتم اختيار صفوف الإجراءات بهذه الطريقة أبدًا. ينقل ArrowDown التركيز إلى أول صف مفعّل، بما في ذلك الإجراءات. تؤدي مغادرة البحث إلى مسح المعاينة وaria-activedescendant، حتى عند بقاء النافذة المنبثقة مفتوحة. تؤدي العودة إلى البحث إلى استعادة المعاينة للاستعلام الحالي.
لا يقوم Enter بأي شيء عند وجود استعلام فارغ أو يتكون من مسافات بيضاء فقط، أو عند عدم بقاء أي خيار مؤهل. لا يؤدي تأليف النص باستخدام طريقة إدخال إلى تنشيط خيار أو نقل التركيز باستخدام مفاتيح الأسهم. عند تثبيت الصفوف فوق المطابقات، مثل القيمة الحالية أو صف “بلا”، اعرضها فقط عندما تطابق نص البحث. تظل النافذة المنبثقة مفتوحة عندما لا يتطابق أي خيار. تظل التصفية من مسؤولية المستدعي.
لا يزال OptionItem المستقل يقبل selected وonSelect للمتصلين الذين يتولون التحديد بأنفسهم. تستمد الخيارات المجمعة التحديد من قيمة المجموعة؛ لا تكرر تلك الحالة على الخيار. لا توفر مجموعات التحديد المخصصة إرسال النماذج الأصلي أو إعادة التعيين أو التحقق المطلوب أو سلوك القراءة فقط أو تكامل Field. استخدم Select عند الحاجة إلى تعاقدات النماذج الأصلية هذه.
شبكات الأيقونات
عيّنcolumns على Section لترتيب العناصر في أعمدة شبكة متساوية العرض. يتحكم العدد نفسه أيضًا في التنقل بلوحة المفاتيح: ينتقل Left وRight داخل صف، بينما ينتقل Up وDown بين الصفوف. يتخطى التنقل الخيارات المعطلة ويتبع اتجاه القراءة. عندما لا يبقى خيار مفعّل في العمود، ينتقل Up وDown إلى أقرب خيار مفعّل في الصف التالي. يعيد Up من الصف الأول إلى حقل البحث عندما لا يوجد قسم سابق. يستخدم الصف الأخير القصير آخر عنصر فيه عندما يكون العمود المطلوب مفقودًا. داخل قائمة فرعية، يغلق السهم للخلف القائمة الفرعية عندما لا يبقى أي خيار مفعّل إلى يسارها.
اعرض كل أيقونة باعتبارها OptionItem بتسمية متاحة وزر أيقونة عبر render. استخدم indicator="none" لإظهار التحديد عبر خلفية الزر. يتلقى رد النداء render الحالة { selected, multiple, disabled }؛ استخدمه لتنسيق خلية محددة وتمرير الخصائص والمرجع المتوفرين.
تركيز لوحة المفاتيح
في صفحاتmenu وpicker، تشكل الصفوف موضع توقف واحدًا لمفتاح Tab. تنقل مفاتيح الأسهم التركيز بين الأقسام والإجراءات والخيارات، وينقل المفتاحان Home وEnd إلى أول وآخر صف مفعّل، ما لم يكن حقل البحث عليه التركيز. لا يؤدي نقل التركيز مطلقًا إلى تحديد خيار؛ إذ يؤدي Enter أو Space إلى تنشيط الصف الذي عليه التركيز. تؤدي العودة باستخدام Tab إلى الصفوف إلى الرجوع إلى آخر صف كان عليه التركيز، أو إلى أول صف مفعّل بمجرد اختفاء ذلك الصف. يحتفظ البحث وBack بجوار البحث وأزرار الرأس وعناصر التحكم الأخرى داخل النافذة المنبثقة بمواضع توقف Tab الخاصة بها.
يغلق Tab وShift+Tab عنصر menu، إلى جانب قوائمه الأصلية عندما يكون التركيز في قائمة فرعية. في picker، ينتقل Tab عبر عناصر التحكم في النافذة المنبثقة ويغلق النافذة المنبثقة عند مغادرة التركيز لها. يحتفظ panel بترتيب Tab الأصلي لعناصر التحكم فيه.
الصفحات والقوائم الفرعية
استخدمPage للتنقل الذي يستبدل محتويات النافذة المنبثقة نفسها. غلّف الصفحة الأولى بـ Page id="root"، أو اختر صفحة أولية أخرى باستخدام defaultPage. عيّن page على إجراء للتنقل دون إغلاق. يعيد Back إلى الصفحة السابقة ويستعيد التركيز إلى الصف الذي استدعاها.
تُركَّب الصفحات عند زيارتها لأول مرة وتبقى مركَّبة طوال تلك الجلسة المفتوحة. تؤدي العودة إلى صفحة إلى الحفاظ على بحثها المحلي ومسودات النماذج والأقسام القابلة للتمرير. تكون الصفحات غير النشطة مخفية وخاملة: فهي لا تشارك في التنقل بلوحة المفاتيح أو التركيز أو شجرة إمكانية الوصول، وتكون النوافذ المنبثقة المتداخلة لـ Dropdown غير نشطة.
تبدأ إعادة الفتح جلسة جديدة عند defaultPage بمحتوى جديد، بما في ذلك عندما يكون Content.keepMounted مضبوطًا أو تُعاد فتح النافذة المنبثقة أثناء انتقال الخروج الخاص بها. يُعاد تعيين سجل الصفحات والبحث المحلي والمسودات. تبقى الصفحة الجاري إغلاقها مركَّبة أثناء انتقال الخروج الخاص بها.
تبقى قيم SelectionGroup غير المتحكم بها مخزنة في Root تحت id الثابت لكل مجموعة وتستمر بعد إعادة الفتح. تبقى القيم التي يتحكم بها المستدعي مملوكة للمستدعي. على سبيل المثال، تبقى قيمة بحث مخزنة فوق Content دون تغيير إلى أن يحدّثها المستدعي. ضع حالة البحث المؤقتة أو المسودة في مكوّن داخل Content أو Page عندما ينبغي إعادة تعيينها مع الجلسة؛ واحتفظ بحالة التطبيق الدائمة فوق Content.
يمكن للصفحة تجاوز type الخاص بالجذر. على سبيل المثال، يمكن لقائمة إجراءات أن تفتح صفحة أداة اختيار قابلة للبحث أو لوحة نموذج. يتلقى البحث التركيز عند الدخول إلى صفحة قابلة للبحث؛ وتركّز الصفحات الأخرى على صفها الأول بعد Back.
useDropdownPage في مكون معروض داخل الجذر. تعيد page الحالية، وgoToPage(page)، وgoBack()، وcanGoBack، وisActive. داخل الصفحة، تكون isActive صحيحة فقط عندما تكون تلك الصفحة نشطة وتكون قائمتها المنسدلة مفتوحة. استخدم isActive لإظهار النوافذ المنبثقة المخصصة للصفحة التي تُعرَض عبر بوابة، بحيث تختفي عندما تصبح الصفحة غير نشطة أو تُغلَق القائمة المنسدلة. على سبيل المثال، يمكن لخيار أن يعود إلى الصفحة السابقة بعد تحديد ما بينما تظل النافذة المنبثقة مفتوحة:
Submenu مع SubmenuTrigger وContent متداخل لقائمة جنبًا إلى جنب. يدخل Arrow Right إلى القائمة الفرعية؛ ويعود Arrow Left إلى القائمة الأصلية. يؤدي تحديد إجراء مغلق إلى إغلاق القائمة المنسدلة بأكملها.
أدوات اختيار متداخلة مستقلة
ضعDropdown.Root آخر داخل Content عندما يفتح عنصر تحكم أداة الاختيار الخاصة به، مثل محدد اتجاه الفرز. يؤدي تحديد خيار داخلي إلى إغلاق أداة الاختيار تلك فقط واستعادة التركيز إلى مشغّلها. يغلق Escape والضغط خارج العنصر طبقة واحدة في كل مرة. استخدم Submenu للأوامر التي يجب أن تغلق شجرة القائمة بأكملها عند تحديدها.
اللوحات والحالة المتحكم بها
استخدمtype="panel" لمدخلات النموذج. يبقي تفاعل الإدخال اللوحة مفتوحة؛ ويمكن لإجراء الحفظ إغلاقها. أدر open وonOpenChange عندما يحتاج مكون آخر أو اختصار إلى فتح القائمة المنسدلة. احتفظ بهذه الحالة مع الميزة التي تنسق التفاعل.
يغلق Escape النافذة المنبثقة ويستعيد التركيز إلى مشغّلها. يؤدي التفاعل الخارجي أيضًا إلى إغلاقها، ولا يؤدي النقر الذي يغلقها إلى تنشيط ما يقع عليه. تبقى المفاتيح المضغوطة داخل النافذة المنبثقة بداخلها، باستثناء اختصارات Ctrl أو Cmd التي لا تعالجها القائمة المنسدلة، لكي تستمر اختصارات مستوى الصفحة في العمل. يقبل Content خيارات التركيز والبوابة من Popover، بما في ذلك هدف صريح لإعادة التركيز لمسارات عمل المحرر.
الإغلاق
يغلق Escape والضغط خارج النافذة المنبثقة والخروج منها باستخدام Tab القائمة المنسدلة. مررonEscapeKeyDown أو onInteractOutside إلى Root للتفاعل قبل إغلاقها، واستدعِ event.preventDefault() لإبقائها مفتوحة. event.target هو العنصر الذي تم الضغط عليه خارجًا، أو null عندما يغادر التركيز باستخدام Tab، وevent.type هو نوع حدث DOM الذي شغّله، مثل touchmove للتمرير السريع خارج النافذة المنبثقة. يصل الضغط الخارجي الذي مُنع إلى العنصر الذي يقع عليه رغم ذلك.
الإرساء دون مشغّل
يمكن أن يُفتح الجذر دونTrigger، على سبيل المثال كقائمة سياق. تحكم فيه باستخدام open وonOpenChange، ومرر anchor إلى Content: عنصر، أو ref، أو عنصر افتراضي يعيد مستطيلًا بإحداثيات إطار العرض. امنح Content قيمة aria-label، إذ لا يوجد مشغّل لتسميته باسمه. عند الإغلاق، يعود التركيز إلى العنصر الذي كان مركّزًا عليه عند فتح النافذة المنبثقة.
useDropdownPlacementOrThrow داخل Dropdown.Content لقراءة قيمتَي side وalign المحسومتين، بما في ذلك الانقلابات الناتجة عن التصادمات. استخدم الجانب المحسوم لوضع عناصر التحكم في البحث والإنشاء الخاصة بالمنتقي بجانب المشغّل. أبقِ عناصر التحكم بترتيبها المرئي في DOM لكي تتبع التنقلات باستخدام لوحة المفاتيح التخطيط. يتلقى البحث الموجود أسفل النتائج التركيز من ArrowDown عند النتيجة الأخيرة؛ ويؤدي ArrowUp من ذلك البحث إلى العودة إلى النتيجة الأخيرة.
التسميات
يمتلك كل جزء نصه: وفّرSearch.placeholder وأسماء المتاحة الأصلية وسمات Close المتاحة والعناصر التابعة لـ Back وLoading وEmpty. القيمة الافتراضية لـ Back هي Back؛ ولا تحتوي حالتا التحميل والفراغ على رسالة مضمّنة. تقبل أجزاء العنصر shortcutJoinLabel لاستبدال then الافتراضي بين خطوات الاختصارات المتسلسلة. يكون لـ aria-labelledby الأصلي الأولوية على aria-label.
الإزاحة
Dropdown.Root
boolean
Whether the popup is initially open when uncontrolled.
string
ID of the
Page shown when the popup opens. Closing the popup resets the page history to it. Defaults to root.boolean
Default for standalone options. Use
SelectionGroup.multiple for independently owned selection values.((event: DropdownDismissEvent) => void)
Called when Escape is about to close the popup. Call
event.preventDefault() to keep it open.((event: DropdownDismissEvent) => void)
Called when a press outside the popup, or Tab out of it, is about to close it.
event.target is the element pressed outside, or null after Tab, and event.type is the type of the DOM event that triggered it. Call event.preventDefault() to keep it open.((open: boolean) => void)
Called with the next open state when the popup opens or closes.
boolean
Whether the popup is open. Use with
onOpenChange to control it."menu" | "panel" | "picker"
مطلوب
Interaction model:
menu for commands and links, picker for search and selectable options, or panel for forms. It sets the ARIA roles, initial focus, and keyboard navigation.Dropdown.Trigger
string | ((state: PopoverTriggerState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
number
افتراضي:"0"
How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.Requires the
openOnHover prop.number
افتراضي:"300"
How long to wait before the popover may be opened on hover. Specified in milliseconds.Requires the
openOnHover prop.string
ID of the trigger. In addition to being forwarded to the rendered element,
it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot
triggerId prop).boolean
افتراضي:"true"
Whether the component renders a native
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (e.g. <div>).boolean
افتراضي:"false"
Whether the popover should also open when the trigger is hovered.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTriggerState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Dropdown.Content
"center" | "end" | "start"
افتراضي:"start"
Alignment along the anchor. Defaults to start.
number | OffsetFunction
افتراضي:"0"
Offset along the alignment axis. Accepts a number or positioning function.
Element | VirtualElement | RefObject<Element | null> | (() => Element | VirtualElement | null) | null
An element to position the popup against.
By default, the popup will be positioned against the trigger.
string | ((state: PopoverPopupState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
Padding
افتراضي:"5"
Additional space to maintain from the edge of the collision boundary.
HTMLElement | ShadowRoot | RefObject<HTMLElement | ShadowRoot | null> | null
Portal destination, using the scoped theme when omitted. Explicit null waits for a target, matching Popover.Portal.
boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | HTMLElement | null)
Determines the element to focus when the popover is closed.
false: Do not move focus.true: Move focus based on the default behavior (trigger or previously focused element).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse,touch,pen, orkeyboard). Return an element to focus,trueto use the default behavior,nullto fall back to the default behavior, orfalse/undefinedto do nothing.
boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null)
Determines the element to focus when the popover is opened.
By default, focus moves to the first tabbable element inside the popup, except when the popover
is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.
false: Do not move focus.true: Move focus based on the default behavior (first tabbable element or popup).RefObject: Move focus to the ref element.function: Called with the interaction type (mouse,touch,pen, orkeyboard). Return an element to focus,trueto use the default behavior,nullto fall back to the default behavior, orfalse/undefinedto do nothing.
boolean
افتراضي:"false"
Keeps the popup mounted while closed.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverPopupState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render."bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"
افتراضي:"bottom"
Preferred side of the anchor. Defaults to bottom, or inline-end in a submenu.
number | OffsetFunction
افتراضي:"0"
Distance from the anchor. Defaults to 0. Accepts a number or positioning function.
CSSProperties | ((state: PopoverPopupState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Width<string | number>
افتراضي:"200"
CSS width of the popup. Numbers are in pixels.
Dropdown.ActionItem
ReactNode
Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row.
"always" | "hover"
Whether trailing actions appear on hover or remain visible. Defaults to
hover.string
CSS class applied to the row.
boolean
افتراضي:"true"
Closes the dropdown after activation, along with parent menus when inside a submenu. Ignored when
page is set."danger" | "neutral"
Color of the text and icons.
danger marks a destructive action.ReactNode
Supporting text, placed according to
descriptionPlacement."below" | "end" | "inline"
Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
ReactNode
Icon rendered after the content.
boolean
افتراضي:"false"
Whether the button should be focusable when disabled.
Shows a chevron indicating that the item opens a submenu.
boolean
افتراضي:"true when render is omitted; false otherwise"
Whether the component renders a native
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).string
ID of the
Page to show on activation. The popup stays open, and the row shows a chevron by default.ReactElement<unknown, string | JSXElementConstructor<any>>
Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref.
ShortcutDefinition
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
string
Text between sequential shortcut steps. Defaults to
then.ReactNode
Icon rendered before the content.
CSSProperties
Inline styles applied to the row.
Dropdown.OptionItem
ReactNode
Trailing controls rendered beside the primary row control. Only supported in picker and panel pages, since a menu may only contain menu items. Secondary actions activate independently of the row.
"always" | "hover"
Whether trailing actions appear on hover or remain visible. Defaults to
hover.string
CSS class applied to the row.
boolean
Overrides the nearest group close policy for this option. A cancelled selection never closes automatically.
"danger" | "neutral"
Color of the text and icons.
danger marks a destructive action.ReactNode
Supporting text, placed according to
descriptionPlacement."below" | "end" | "inline"
Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
ReactNode
Icon rendered after the content.
boolean
افتراضي:"false"
Whether the button should be focusable when disabled.
Shows a chevron indicating that the item opens a submenu.
"check" | "checkbox" | "none"
Selection indicator: a check icon after the content, a checkbox before it, or none. Defaults to
checkbox when multiple is set, otherwise check, and to none when selected is omitted.boolean
افتراضي:"true when render is omitted; false otherwise"
Whether the component renders a native
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).((eventDetails: DropdownSelectionGroupChangeEventDetails) => void)
Called before the nearest group commits selection, with
event, reason, trigger, cancel and isCanceled. Calling cancel() prevents the value change and automatic close.ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DropdownOptionItemState>
Element or function rendered as the row. Functions receive the supplied props and
{ selected, multiple, disabled } state. Forward the props and ref to the rendered control.boolean
Selected state for standalone options. Options inside a
SelectionGroup derive it from their owner. Grouped picker options expose aria-selected, menu options expose aria-checked, and panel options expose aria-pressed.ShortcutDefinition
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
string
Text between sequential shortcut steps. Defaults to
then.ReactNode
Icon rendered before the content.
CSSProperties
Inline styles applied to the row.
string
Stable option identifier within its nearest
SelectionGroup. The group supplies selected state and commits this value on activation.Dropdown.SelectionGroup
boolean
Default close policy for owned options: true for single selection, false for multiple selection. Individual options can override it.
string | string[] | null
Initial uncontrolled selection. Defaults to null for single selection and an empty array for multiple selection.
string
Stable identifier unique within the dropdown root. Required for uncontrolled groups, whose values persist under it across popup close and page navigation. Optional for controlled groups.
boolean
Uses an array of selected identifiers when true. Otherwise the value is one identifier or null.
((value: string | null, eventDetails: DropdownSelectionGroupChangeEventDetails) => void) | ((value: string[], eventDetails: DropdownSelectionGroupChangeEventDetails) => void)
Called with the next value and cancellable event details:
event, reason, trigger, cancel and isCanceled. Calling cancel() preserves the value and keeps the popup open. Repeated single selection does not emit another change.ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, DropdownSelectionGroupState>
Element or function rendered as the group. Functions receive supplied props and
{ value, multiple } state. Forward the props and ref.string | string[] | null
Controlled selection: a string or null for single selection, or an array for multiple selection. Undefined leaves selection uncontrolled.
Dropdown.Search
string | ((state: InputState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
string | number | readonly string[]
The default value of the input. Use when uncontrolled.
boolean
افتراضي:"false"
Shows the search input focus outline. Defaults to false for all dropdown searches. Set true to opt in. Error styling remains visible.
((value: string) => void)
Called with the search text on every change. The application filters the results.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, InputState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.CSSProperties | ((state: InputState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
"end" | "start"
Aligns text to the logical start or end of the input. Follows the text direction.
string | number | readonly string[]
The value of the input. Use when controlled.
Dropdown.Header
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.Dropdown.Title
string | ((state: PopoverTitleState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverTitleState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.CSSProperties | ((state: PopoverTitleState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Dropdown.Close
string
مطلوب
Accessible name of the close control. Required because the default control only shows an icon.
string | ((state: PopoverCloseState) => string | undefined)
CSS class applied to the element, or a function that
returns a class based on the component’s state.
boolean
افتراضي:"true"
Whether the component renders a native
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, PopoverCloseState>
Allows you to replace the component’s HTML element
with a different tag, or compose it with another component.Accepts a
ReactElement or a function that returns the element to render.CSSProperties | ((state: PopoverCloseState) => CSSProperties | undefined)
Style applied to the element, or a function that
returns a style object based on the component’s state.
Dropdown.Page
string
مطلوب
Identifier matched by
defaultPage, the page prop of actions, and goToPage. The page renders only while it is current."menu" | "panel" | "picker"
Interaction model while the page is shown. Defaults to the root
type.Dropdown.Back
string
CSS class applied to the row.
"danger" | "neutral"
Color of the text and icons.
danger marks a destructive action.ReactNode
Supporting text, placed according to
descriptionPlacement."below" | "end" | "inline"
Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
ReactNode
Icon rendered after the content.
boolean
افتراضي:"false"
Whether the button should be focusable when disabled.
Shows a chevron indicating that the item opens a submenu.
boolean
افتراضي:"true when render is omitted; false otherwise"
Whether the component renders a native
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).ReactElement<unknown, string | JSXElementConstructor<any>>
Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref.
ShortcutDefinition
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
string
Text between sequential shortcut steps. Defaults to
then.ReactNode
Icon rendered before the content.
CSSProperties
Inline styles applied to the row.
Dropdown.Submenu
Whether the popup is initially open when uncontrolled.
ID of the
Page shown when the popup opens. Closing the popup resets the page history to it. Defaults to root.Default for standalone options. Use
SelectionGroup.multiple for independently owned selection values.Called with the next open state when the popup opens or closes.
Whether the popup is open. Use with
onOpenChange to control it.Interaction model:
menu for commands and links, picker for search and selectable options, or panel for forms. It sets the ARIA roles, initial focus, and keyboard navigation.Dropdown.SubmenuTrigger
CSS class applied to the row.
Delay in milliseconds before a submenu opened on hover closes. Requires
openOnHover. Defaults to 0.Color of the text and icons.
danger marks a destructive action.Delay in milliseconds before the submenu opens on hover. Requires
openOnHover. Defaults to 300.Supporting text, placed according to
descriptionPlacement.Places supporting content inline after the label, at the end, or below it with wrapping. Inline is the default.
Icon rendered after the content.
Whether the button should be focusable when disabled.
Shows a chevron indicating that the item opens a submenu.
Whether the component renders a native
<button> element when replacing it
via the render prop.
Set to false if the rendered element is not a button (for example, <div>).Also opens the submenu when the row is hovered.
Element rendered as the row instead of a native button. Custom components must forward the supplied props and ref.
Keyboard shortcut keys displayed at the end of the row. Registering the
shortcut is up to the application.
Text between sequential shortcut steps. Defaults to
then.Icon rendered before the content.
Inline styles applied to the row.
Dropdown.Section
number
Number of grid columns. Sets the grid layout and enables horizontal arrow navigation and vertical movement by row.
ReactNode
Heading displayed above the rows. It also names the group for assistive technologies.
boolean
Caps the section height and scrolls its rows. Nest labelled sections inside it to scroll them as one list.
Dropdown.Separator
string
Class applied to the separator. Native div attributes and refs are also accepted.
Dropdown.Loading
ReactNode
Loading message announced as a polite, busy status.
string
Class applied to the status. Native div attributes and refs are also accepted.
Dropdown.Empty
ReactNode
Empty-state message announced as a polite status.
string
Class applied to the status. Native div attributes and refs are also accepted.