Twilight docs

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

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

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

Example

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 />
  );
}

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

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`

Used inside: <salla-bullet-delivery>, <salla-delivery-promise>, <salla-gifting>.

salla-searchable-dropdown

Use itCopy Anchor Link

ExampleCopy Anchor Link

PropertiesCopy Anchor Link

EventsCopy Anchor Link

RelatedCopy Anchor Link

On this page

Use it

Example

Properties

Events

Related