قائمة منسدلة

Dropdown

حقل قائمة منسدلة في React باختيار مفرد ومتعدّد، وبحث داخل اللوحة، وخيارات مجمّعة، وربط كامل للحقل. مبني على cmdk للتصفية السريعة بالعربية والإنجليزية.

افتح في ستوري بوك ↗

Dropdown حقل اختيار يتركب من عناصر DropdownItem. أضف multiple للتحديد المتعدد أو searchable لمرشح داخل اللوحة.

متى تستخدمه

استخدم Dropdown حين يحتاج حقل الاختيار إلى بحث أو قيم متعدّدة أو خيارات مجمّعة: اختيار عدّة خدمات، أو التصفية حسب مدن كثيرة، أو الانتقاء من قائمة مرجعية طويلة. استخدم Select للاختيار المفرد البسيط وChip لمجموعة مرشّحات ظاهرة.

وفّر emptyMessage ليبقى البحث بلا نتائج مفهومًا.

أمثلة

اختيار مفرد

المدينة

قابل للبحث

الدولة

اختيار متعدّد

الخدمات

خيارات مجمّعة

حزمة التقنيات

الخصائص

الخصائص التي يعرّفها Dropdown. سمات العنصر الأصلي تمرّ كما هي.

<Dropdown>

الخاصية	النوع	الوصف
`size`	`"md" \| "lg"`
`variant`	`"default" \| "filled-lighter" \| "filled-darker"`
`open`	`boolean`
`defaultOpen`	`boolean`
`onOpenChange`	`(open: boolean) => void`
`label`	`react.ReactNode`	Visible label above the trigger.
`helperText`	`react.ReactNode`	Hint shown below the trigger when there's no error.
`errorMessage`	`react.ReactNode`	Message shown below the trigger when `error` is true.
`error`	`boolean`	Marks the field invalid - sets `aria-invalid` and the error border.
`required`	`boolean`	Adds the required asterisk + `aria-required`.
`disabled`	`boolean`	Disables the trigger entirely.
`readOnly`	`boolean`	Shows the value but blocks opening (SDGA Read-only).
`placeholder`	`react.ReactNode`	Placeholder shown when nothing is selected.
`searchable`	`boolean`	Render the in-panel filter input (combobox behavior). Off by default - the plain SDGA dropdown. A hidden focusable input is kept either way for cmdk's keyboard model.
`searchPlaceholder`	`string`	Placeholder for the filter input when `searchable`.
`emptyMessage`	`react.ReactNode`	Shown when a filter matches nothing.
`getLabel`	`(value: string) => ReactNode`	Override the trigger label resolver (e.g. async-loaded options).
`id`	`string`
`className`	`string`
`aria-label`	`string`
`aria-labelledby`	`string`
`children`إلزامي	`react.ReactNode`	`<DropdownItem>` (+ optional `DropdownGroup` / `DropdownSeparator`).
`multiple`	`false`
`value`	`string`
`defaultValue`	`string`
`onValueChange`	`(value: string) => void`

<DropdownItem>

الخاصية	النوع	الوصف
`value`إلزامي	`string`	Stable value for filtering + selection.
`keywords`	`string[]`	Extra search terms cmdk matches against the filter input.
`disabled`	`boolean`	Whether this item is currently disabled.
`onSelect`	`(value: string) => void`	Fires alongside the root's `onValueChange`.
`children`	`ReactNode`
`asChild`	`boolean`
`forceMount`	`boolean`	Whether this item is forcibly rendered regardless of filtering.

<DropdownGroup>

الخاصية	النوع	الوصف
`heading`	`react.ReactNode`	Optional heading to render for this group.
`children`	`ReactNode`
`asChild`	`boolean`
`value`	`string`	If no heading is provided, you must provide a value that is unique for this group.
`forceMount`	`boolean`	Whether this group is forcibly rendered regardless of filtering.

<DropdownSeparator>

الخاصية	النوع	الافتراضي	الوصف
`asChild`	`boolean`
`alwaysRender`	`boolean`		Whether this separator should always be rendered. Useful if you disable automatic filtering.

إمكانية الوصول

يعرض المشغّل aria-haspopup، وتستخدم تسمية الحقل والنص المساعد والخطأ الربط نفسه في TextInput. داخل اللوحة يتّبع حقل البحث وقائمة الخيارات نمط combobox من cmdk: مفاتيح الأسهم تتنقّل بين الخيارات، وEnter يبدّل الخيار المظلّل، وEscape يغلق.

تُعلن القيم المختارة، وفي وضع الاختيار المتعدّد يبقى كل اختيار ظاهرًا في المشغّل.