Selection

Selection is a family of accessible native select alternatives that makes it easy to choose one or more options from a list. Selection exports the "Dropdown" component.

Usage

Dropdown accepts an array of options where each option is an object containing at least 2 properties, id & key.

import { Dropdown } from "@asphalt-react/selection"

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

  return <Dropdown items={items} />
}

Dropdown

A Dropdown shows the list of options in a popover for the users to select from. You can filter options in the list and set initial selected options and also select all the options at once. Dropdown supports custom ordering of the selected options, reseting it to the initial state and set it to be open on the initial render.

A dropdown mainly consists of 3 parts.

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

items

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.

Multi-select and filtering options

Apply the multiSelect prop when you want your user to select more than one option. To enable filtering among the options, use the typeahead prop.

Enhancing the options

To enhance the option's caption, you can add a custom element, such as an Avatar, along with the caption. For example, showing avatars/initials for a list of users. Use the getAddonStart and getAddonEnd to enable the behavior.

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. It works only with multiselect enabled Dropdown.

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",
   initialSelected: false     // true if this item should be initially selected
   selectionOrder: 0   // a valid integer to specify the order of the item in the tags list.
}

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

| type | required | default | | ------- | -------- | ------- | | arrayOf | true | N/A |

onChange

Callback to handle the item selection event. Ivokes on user interaction or the Dropdown reset. It has the following signature

• item - item selected by user interaction
• options - an options bucket with the following properties
  • ref: React ref for the Dropdown
  • selectedItems: an array of all the selected items in case of multiselect enabled Dropdown

 (item, { ref, selectedItems }) => void

| type | required | default | | ---- | -------- | ------- | | func | false | N/A |

multiSelect

Enables multiple item selection

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

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 |

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 |

onBlur

Callback to handle blur event 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 |

initialIsOpen

Opens Dropdown on initialization

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

disabled

Disables the Dropdown.

| type | required | default | | ---- | -------- | ------- | | bool | false | false |

placeholder

Hint text to show when no item is selected.

| type | required | default | | ------ | -------- | -------- | | string | false | "Select" |

invalid

Applies invalid styles to the Dropdown.

| type | required | default | | ---- | -------- | ------- | | bool | false | N/A |

displayKey

Dropdown uses this prop to render the caption of the list item instead of the "key" property.

const item = [
{
 id: 1,
 label: "Bali",
},
{
 id: 2,
 label: "Jakarta"
}]

function App () {
 return <Dropdown items={items} displayKey="label" />
}

| type | required | default | | ------ | -------- | ------- | | string | false | "key" |

flip

Dropdown flips according to viewport boundary if there isn't space to render the popover.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

filter

Dropdown shows the filtered items in a typeahead enabled Dropdown by default. Set this prop's value to false to show all the items instead.

The matched items appear at the top of the list followed by the rest of the items.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

translate

Function to show custom text in selectionBox in multiSelect enabled Dropdown.

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

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.

| type | required | default | | ---- | -------- | ------- | | bool | false | true |

getAddonStart

Use this function to return an element to render as the prefix for the list item. It receives the item as the argument to uniquely identify the list item.

const itemAvatar = (item) => {
 const caption = item.key.substring(0,2)

 return <Avatar uppercase>{caption}</Avatar>
}

function App () {
 return <Dropdown getAddonStart={itemAvatar} />
}

| type | required | default | | ---- | -------- | ------- | | func | false | N/A |

getAddonEnd

Use this function to return an element to render as the suffix for the list item. It receives the item as the argument to uniquely identify the list item.

const itemAvatar = (item) => {
 const caption = item.key.substring(0,2)

 return <Avatar uppercase>{caption}</Avatar>
}

function App () {
 return <Dropdown getAddonEnd={itemAvatar} />
}

| type | required | default | | ---- | -------- | ------- | | func | false | N/A |

selectAll

Renders a special item in the list that allows the user to select or deselect all the options in the Dropdown. It accepts a boolean value or a node.

Acceptable value:

• true: enables the select all feature and uses "select all" as the caption for the item.
• false: skips the select all feature.
• node: enables the select all feature and uses the element as the caption for the item.

import {Text} from "@asphalt-react/typography"

<Dropdown selectAll={<Text>Pilih Semua</Text>} />

| type | required | default | | ----- | -------- | ------- | | union | false | false |