# salla-searchable-dropdown (https://docs.salla.dev/twilight/react/web-components/salla-searchable-dropdown)



{/* Generated by scripts/sync-web-components.mjs from the components docs.json. Do not edit by hand. */}

A combobox-style dropdown with an optional search box. Salla components such as salla-delivery-promise,
salla-bullet-delivery and salla-gifting use it for city and country pickers. It is controlled: you pass `items` and `selected-item`,
and update them yourself when it emits `itemSelected` or `searchInput`.
Use it in a theme when you need a single-choice list that is too long for a native select.

Item names are shown in English (`name_en`) when the store language is not Arabic and `name_en` is set,
otherwise `name` is shown.

Accessibility: the trigger has `role="combobox"` with `aria-expanded`, the list has `role="listbox"`
and items have `role="option"` with `aria-selected`. The trigger opens with Enter, Space or ArrowDown,
ArrowUp and ArrowDown move through the items, Enter selects the highlighted item and Escape closes the list.

## Use it [#use-it]

In HTML or JSX, use the tag `<salla-searchable-dropdown>` with the **Attribute** names below. In React, the wrapper takes the **Property** names (camelCase).

```tsx
import { SallaSearchableDropdown } from '@salla.sa/twilight-components-react/searchable-dropdown';
```

## Example [#example]

```tsx
import { useEffect } from 'react';
import { SallaSearchableDropdown } from '@salla.sa/twilight-components-react/searchable-dropdown';

export function Example() {
  useEffect(() => {
    const dropdown = document.querySelector('#city');
    dropdown.items = [{ id: 1, name: 'الرياض', name_en: 'Riyadh' }, { id: 2, name: 'جدة', name_en: 'Jeddah' }];
    dropdown.clientSearch = true;
    dropdown.addEventListener('itemSelected', e => { dropdown.selectedItem = e.detail; });
  }, []);

  return (
    <SallaSearchableDropdown id="city" label="City" placeholder="Select a city" inputId="city-input" required />
  );
}
```

```html
<salla-searchable-dropdown id="city" label="City" placeholder="Select a city" input-id="city-input" required></salla-searchable-dropdown>
<script>
  const dropdown = document.querySelector('#city');
  dropdown.items = [{ id: 1, name: 'الرياض', name_en: 'Riyadh' }, { id: 2, name: 'جدة', name_en: 'Jeddah' }];
  dropdown.clientSearch = true;
  dropdown.addEventListener('itemSelected', e => { dropdown.selectedItem = e.detail; });
</script>
```

## Properties [#properties]

| Property           | Attribute            | Description                                                                                                                                                                                                                          | Type             | Default |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------- | ------- |
| `clientSearch`     | `client-search`      | When true, the component filters `items` itself as the user types (case-insensitive match on `name` and `name_en`, with Arabic alef variants treated as equal). When false, it only emits `searchInput` and you must update `items`. | `boolean`        | `false` |
| `disabled`         | `disabled`           | Prevents opening the dropdown and removes the trigger from the tab order.                                                                                                                                                            | `boolean`        | `false` |
| `dropUp`           | `drop-up`            | Opens the list above the trigger instead of below it.                                                                                                                                                                                | `boolean`        | `false` |
| `inputId`          | `input-id`           | Used as the `id` of the search input (the label points to it) and as the prefix of the listbox id (`<input-id>-listbox`). Set a unique value per dropdown on the page.                                                               | `string`         | `''`    |
| `items`            | `items`              | Options to list. Each item is `{ id: number \| string, name: string, name_en?: string }`. Set as a JS property, not an HTML attribute.                                                                                               | `DropdownItem[]` | `[]`    |
| `keepParentScroll` | `keep-parent-scroll` | When true, the dropdown will NOT override the nearest scrollable ancestor's `overflow` to `visible` while open. Use this when the host (e.g. a modal body) needs to keep its own scrolling intact while the dropdown is open.        | `boolean`        | `false` |
| `label`            | `label`              | Label text shown above the trigger. Nothing is rendered when empty.                                                                                                                                                                  | `string`         |         |
| `loading`          | `loading`            | Disables the whole dropdown (it cannot be opened) and shows a spinner in place of the list.                                                                                                                                          | `boolean`        | `false` |
| `noResultsText`    | `no-results-text`    | Text shown when the list is empty. Falls back to the translated "no options" message, then to "No results found".                                                                                                                    | `string`         | `''`    |
| `placeholder`      | `placeholder`        | Text shown in the trigger when nothing is selected, and as the placeholder of the search input.                                                                                                                                      | `string`         | `''`    |
| `required`         | `required`           | Adds a red asterisk after the label. It is visual only and does not validate anything.                                                                                                                                               | `boolean`        | `false` |
| `searchQuery`      | `search-query`       | Value shown in the search input when `client-search` is off. Use it to keep the typed text in sync with a server-side search.                                                                                                        | `string`         | `''`    |
| `searchable`       | `searchable`         | Shows the search input inside the open list. Set to false for a plain select-like list.                                                                                                                                              | `boolean`        | `true`  |
| `searching`        | `searching`          | Shows a spinner in place of the list while the dropdown is open. Use it while you fetch results for a `searchInput` event.                                                                                                           | `boolean`        | `false` |
| `selectedItem`     | `selected-item`      | The currently selected item, shown in the trigger and marked in the list. The component does not set it itself, so update it from the `itemSelected` event.                                                                          | `DropdownItem`   | `null`  |

## Events [#events]

Listen with `addEventListener`, or the `on` prop of the React wrapper (for example `onModalBack`).

| Event            | Description                                                                                                | Detail         |
| ---------------- | ---------------------------------------------------------------------------------------------------------- | -------------- |
| `dropdownClosed` | Fires when the list closes, by selection, outside click or Escape. `event.detail` is empty.                | `void`         |
| `dropdownOpened` | Fires when the list opens. `event.detail` is empty.                                                        | `void`         |
| `itemSelected`   | Fires when the user picks an item. `event.detail` is the selected item object. The list closes afterwards. | `DropdownItem` |
| `searchInput`    | Fires on every keystroke in the search input. `event.detail` is the current text.                          | `string`       |

## Related [#related]

Used inside: [`<salla-bullet-delivery>`](https://docs.salla.dev/twilight/react/web-components/salla-bullet-delivery), [`<salla-delivery-promise>`](https://docs.salla.dev/twilight/react/web-components/salla-delivery-promise), [`<salla-gifting>`](https://docs.salla.dev/twilight/react/web-components/salla-gifting).