@asphalt-react/dropdown v1.23.3

Dropdown

An accessible native select alternative that makes it easy to choose one or more options.

A dropdown mainly consists of 3 parts.

• SelectionBox - holds the selected value
• ListBox - holds the options
• ListItem - the option itself

You would typically pass an array of options where each option is an object containing at least 2 properties, id & key.

let items = [{ id: "1", key: "Apple"}, { id: "2", key: "Banana" }, ...]

The id property is how Dropdown identifies & knows the item. Naturally, it should be unique. The key property's value will be shown as the list item, so users can easily identify the option they would like to choose.

Dropdown supports multiple selection and search on items. Can also be kept open initially and provides the ability to reset programmatically.

Usage

import Dropdown from "@asphalt-react/dropdown"

function App() {
  let items = [
    { id: "1", key: "Bangalore" },
    { id: "2", key: "Delhi" },
  ]

  return <Dropdown items={items} />
}

Multiselect

Apply the multiSelect prop when you want your user to select more than one item. To enable search with multiselect apply the typeahead prop.

For multiselect, use initialSelectedItems instead of initialSelectedItem.

ListBox Flipping

By default ListBox opens up below the SelectionBox. ListBox flips in the opposite side if there is not enough space to render, it improves user experience on small screens.

To disable this behavior, set flip to false.

ListBox flipping doesn't work with multiSelect.

Avatar

A ListItem can render an Avatar component or an image as a prefix. For example, showing avatars/initials for a list of users.

i18n

Internationalization is the process of designing and preparing your app to be usable in different languages. SelectionBox text supports l10n and can be achieved using translate.

translate  only works with the multiSelect.

Accessibility

• Use Tab to focus the Dropdown.
• Use any of ↓ , ↑ , Enter to open the listbox.
• Use ↓ to navigate down the list.
• Use ↑ to navigate up the list.
• Use shift + ↓ to navigate 5 times down the list.
• Use shift + ↑ to navigate 5 times up the list.
• Use Enter to select an option from the list.
• Use Esc to close the list.

Data Attributes

The Dropdown allows passing data-* attributes to the top level element of Dropdown. data-* are used by Dropdown to identify each of its instances and test its behavior. Dropdown's internal elements have a data-testid attribute which are used for testing purposes.

Props

items

Array of Objects that dropdown renders

items = [{key: "jakarta", key: "1"}, ...]

placeholder

Hint text to show when no item is selected

onChange

Called when selected item changes by user interaction or the dropdown resets. It receives multiple arguments with the following signature

• item - item selected by user interaction
• options(object) - selectedItems key gives an array of selectedItems when multiSelect

 (item, options) => void

size

renders the component with the provided size. accepts s, m, l for small, medium & large

stretch

Stretches the component width to match its container

defaultHighlightedIndex

This is the index value of an item which will be highlighted when dropdown is initialized or reset

initialSelectedItem

Item which should be pre-selected on initialization. Applies for the first render only.

Note: This prop is going to be deprecated in next major version

initialSelectedItems

Items which should be pre-selected for multiSelect on initialization. Applies for the first render only.

Note: This prop is going to be deprecated in next major version

initialIsOpen

Opens dropdown on initialization

elevation

z-index of list box

disabled

Disables the dropdown

invalid

Applies invalid styles to the dropdown

displayKey

Key property name of the items, the key property's value will be shown as the list item .

flip

Dropdown flip according to viewport boundary

multiSelect

Enables multiple item selection

translate

Function to show custom text in selectionBox in multiSelect

id

id of the dropdown

labelId

Id of the label used for dropdown. Used for aria attributes.

resetRef

Custom reference for reset.

reset does not clear the dropdown. It resets the dropdown to its first render. Only works with initialSelectedItem or initialSelectedItems

Note: This prop is going to be deprecated in next major version

typeahead

Enables a typeahead / search

emptyText

Show custom text when no result is found