@asphalt-react/selection v2.0.0-rc.7

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.

Controlled

Apply controlled props to manage the items' state from the application. When you enable controlled props, ensure the following:

• Include the selected key in the items props.
• Use onControlledChange instead of onChange to receive information about the currently selected item and the type of action (selecting or unselecting).
• Update items state from the application using returned value from onControlledChange event.
• Note that initialSelected in items props will not take effect.

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.

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 }) => {}

controlled

Dropdown gives you the control of its internal state. Use this prop to manage the selection of items.

onControlledChange

Callback to handle the item selection/de-selection for controlled Dropdown. Invokes on user interaction or tag deletion. It has the following signature:

(item, { ref, selection, changedItems }) => {}

• item - The item that the user interacted with. If the user opts for the "select-all" option, the item is null.
• options - an options bucket with the following properties:
  • ref: React ref for the Dropdown
  • selection: Boolean value to represent item selection/deselection (true/false)
  • changedItems: only present when the user opts for select all. An array of all the items that should change its state. Use the selection key to determine whether the changedItems were selected or de-selected.

multiSelect

Enables multiple item selection

typeahead

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

onInput

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

(event) => {}

onBlur

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

(event) => {}

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

initialIsOpen

Opens Dropdown on initialization

disabled

Disables the Dropdown.

placeholder

Hint text to show when no item is selected.

invalid

Applies invalid styles to the Dropdown.

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" />
}

flip

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

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.

translate

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

id

DOM id of the Dropdown.

labelId

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

emptyText

Show custom text when no result is found.

tags

Shows the selected items as tags above a multiselect dropdown.

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

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

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