@asphalt-react/dropdown

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 filtering on items. Can also be kept open initially and provides the ability to reset programmatically. You may also choose in which order selected items are rendered. This can be useful for cases where you want to retain & restore the original order of user selection.

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 filtering 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.

Keyboard interactions

The Dropdown component is completely keyboard friendly. It is engineered in such a way that the user never needs to move their hand to the mouse, if they so desire.

• 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 = [{ id: "1", key: "jakarta", ...]

Complete shape of each object may look like:

{
   id: "string-to-uniquely-identify-the-item",
   key: "DisplayValue",
   selected: false     // true if this item should be selected
   selectionOrder: 0   // a valid integer to specify the order
}

Out of the above only id is required. Typically, at the least, provide id and key.

type	required	default
arrayOf	true	N/A

placeholder

Hint text to show when no item is selected

type	required	default
string	false	"Select"

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

type	required	default
func	false	N/A

onInput

Callback to handle user input in a typeahead enabled Dropdown. It receives the React synthetic event as the argument.

(event) => {}

type	required	default
func	false	N/A

size

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

type	required	default
enum	false	"m"

stretch

Stretches the component width to match its container

type	required	default
bool	false	false

defaultHighlightedIndex

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

type	required	default
number	false	0

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

type	required	default
object	false	N/A

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

type	required	default
arrayOf	false	[]

initialIsOpen

Opens Dropdown on initialization

type	required	default
bool	false	false

elevation

z-index of list box

type	required	default
number	false	1

disabled

Disables the Dropdown

type	required	default
bool	false	false

invalid

Applies invalid styles to the Dropdown

type	required	default
bool	false	N/A

displayKey

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

type	required	default
string	false	"key"

flip

Dropdown flip according to viewport boundary

type	required	default
bool	false	true

filter

Don't show unmatched typeahead items

When typeahead is applied, only the matching items will show up in the list. Passing false will instead show all the unmatched items after the matched items in the list. This way, you can control if all items are shown in the list or not. As a consequence, if filter is false, then the empty state will never appear.

filter has no effect when typeahead={false}

type	required	default
bool	false	true

multiSelect

Enables multiple item selection

type	required	default
bool	false	false

translate

Function to show custom text in selectionBox in multiSelect

type	required	default
func	false	N/A

id

DOM id of the Dropdown

type	required	default
string	false	N/A

labelId

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

type	required	default
string	false	N/A

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

type	required	default
union	false	N/A

typeahead

Enables filtering of matched items based on typed keywords. The matching algorithm used gives the end user the best possible user experience.

type	required	default
bool	false	false

emptyText

Show custom text when no result is found

type	required	default
string	false	"No Results Found."

tags

Shows the selected items as tags above a multiselect dropdown.

from v1.20.0+

type	required	default
bool	false	true