| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| afterHide | ((e?: Event) => void) | false | ||
| afterShow | (() => void) | false | ||
| beforeHide | BeforeCallback | false | ||
| beforeShow | BeforeCallback | false | ||
| block | boolean | false | ||
| disabled | boolean | false | ||
| error | boolean | false | ||
| footer | ReactNode | false | Prop to define a custom footer for the tiered select. Accepts a Example: | |
| getValueString | GetValueString | false | ||
| i18nScope | string | false | The i18n key to use for the tiered select's configurable strings. Defaults to using the core library's default strings. | |
| loading | boolean | false | ||
| loadingMore | boolean | false | Used to display a loading indicator as the last item of the list. Can
be used with | |
| onClear | ((event: MouseEvent<HTMLButtonElement, MouseEvent>) => void) | false | ||
| onScrollBottom | ((e: UIEvent<HTMLDivElement, UIEvent>) => void) | false | ||
| onSearch | ((event: ChangeEvent<HTMLInputElement>) => void) | false | ||
| options | any[] | false | Flat array of tier objects, this array is used as data for the component | |
| selectableTiers | boolean | false | If true, any tier is selectable. If false, only leaf nodes are selectable | |
| tabIndex | number | false | ||
| value | any[] | false | Flat array of tier objects that represents the selected value | |
| getGroupId | Function | false | Callback for using a custom | |
| getId | Function | false | Callback for using a custom | |
| getLabel | Function | false | Callback for using a custom | |
| getNextGroupId | Function | false | Callback for using a custom | |
| isLeaf | Function | false | ||
| isTierDisabled | Function | false | ||
| onChange | Function | false |
Callback for selecting an item from the tiered select. Returns the{' '}
Selection object from the Menu api, along
with the updated value
| |
| onNavigate | Function | false | Callback for when navigation occurs. Triggered by the left and right
arrow keys, or clicking a navigable item. Returns the id of the next
group that will be navigated to, and the updated path.
| |
| onQuickCreate | Function | false | Pass this callback when a quick create experience is desired. Called
when the "create" button in quick create mode is clicked. Returns the
value of the quick create input.
|
By default, the TieredSelect assumes the data takes the shape seen below. Additionally, getter functions can be supplied to the getId, getGroupId, getNextGroupId, and getLabel props if a custom shape is desired. Important: root groupIds are expected to be null. Leaf nodes are not expected to have a nextGroupId
No Quick Create and all defaulted values
Note: selectableTiers is true by default
The TieredSelect will look to the i18nScope prop to figure out which scope to call in the I18n.t function, like so:
For example,
The following keys can be configured:
The i18n-js package is used internally, so there is no need to pass a t or l function to the I18nProvider, only locale and translations
By providing an array of tiers to the value prop, the TieredSelect can hold an initial value. It looks at the last tier in the value prop, and populates the menu with tiers belonging to the nextGroupId of that last tier. It can also be used in a controlled manner, by using the onChange along with value.
The TieredSelect figures out which items to render by looking through options and filtering by which groupIds match the current tier. The rendered items display whatever getLabel(item) returns.
A special case arises when tiers are not selectable. If the last tier in the value array passed to the TieredSelect is a leaf node, it will open to the parent of the leaf node so that the leaf is displayed as selected. For instance:
An initial value not terminating in a leaf node can also be passed to a TieredSelect with non-selectable tiers. It will open to that tier and show any child nodes of that tier.
When searching a TieredSelect, all possible tiers should be flattened into a single list, and selecting one will fill in the value to the selected value. Due to potentially unknown data shapes, as well as the probable need to make requests for search results, this behavior has been left up to the implementor.
In TieredSelect the onChange will return the a selection object, similar to our Menu onChange api, with an added value key. When searching, the value key will have the value of the value from where the search was performed.
There are many ways to implement the desired UX. The approach below turns all search results into what are essentially value objects (i.e an array of Tier arrays), which it filters then feeds to the TieredSelect when a search is made. This way, the value of the TieredSelect can be set from the selection.item value inside of the onChange callback. The TieredSelect automatically closes after selecting a search result, so the next time it is opened, it will open to the selected value and the normal options will be used.
10.19.0