Intelligent-tree-select

React tree select component based on react-select and virtualization with react-window.

Before start

Before you can use this component you will need Node.js in version 14+, but we recommend using the latest available version.

Getting started

Easiest way is to install via NPM

npm install intelligent-tree-select --save

Then import it

import { IntelligentTreeSelect } from "intelligent-tree-select"
import "intelligent-tree-select/lib/styles.css"

Usage example can be found in examples/demo.js

Intelligent Tree Select Props

Props types are the same as the ones introduced by react-select.

Additional parameters introduced by intelligent-tree-select are:

| Property | Type | Default Value | Description | | :---------------- | :--------------------- | :------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fetchOptions | func | - | Function used to fetch options. See below for argument description. | | fetchLimit | number | 100 | Size of a page loaded in one request via fetchOptions | | searchDelay | number | - | Delay in milliseconds between the input change and fetchOptions invocation. Allows to wait for reasonable user input before actually invoking search on the server. By default the search is invoked with no delay. | | options | Array<Object> | - | Options to render in the menu list. If fetchOptions is not specified (it takes precedence over this property if specified), this property can be used to provide options to select from. Note that it is recommended to memoize them. | | expanded | bool | false | whether the options are expanded by default | | isMenuOpen | bool | false | Whether the menu is open. Setting this to true force menu to me always opened | | multi | bool | true | Whether multiple selection is supported | | maxHeight | number | 300 | Maximum height of the dropdown menu | | minHeight | number | 0 | Minimum height of the dropdown menu | | optionRenderer | React component/func | - | overriding built-in option render component | | valueRenderer | React component/func | - | overriding built-in value render component. Receives the selected option's label and the option itself as parameter (works for both multi and single select). | | optionHeight | number or func | 25px | Option height. Dynamic height can be supported via a function with the signature ({ option: Object }): number | | optionLeftOffset | number | 16px | Option base left offset. Left offset is calculated as depth level of the option * optionLeftOffset | | renderAsTree | bool | true | Whether options should be rendered as a tree. | | noResultsText | string | - | Text displayed when no matching options were found. | | loadingText | string | - | Text displayed while options are being loaded. | | labelKey | string | 'label' | Attribute of an option that contains the display text. | | valueKey | string | 'value' | Attribute of an option that represents the option's value. | | childrenKey | string | 'children' | Attribute of an option that represents its children. | | titleKey | string | 'title' | Attribute of an option that contains the tooltip text. | | getOptionLabel | Function | - | Function to extract label from an option. If specified, overrides labelKey. | | onOptionCreate | function | - | callback when the new option is created. Signature ({ option: Object}): none Currently disabled. | | optionLifetime | string | '5m' | String representing how long the options should be cached. Syntax: XdXhXmXs where X is some number, d stands for days, h hours ,m minutes, s seconds. | | simpleTreeData | bool | true | Whether the options are in a simple format. (One node == one option). In this case, children are just an array of identifiers (values). | | name | string | -- | Unique name for the component. Whenever this prop is set then the options will be cached. | | valueIsControlled | boolean | true | Sets if the passed value is changed over time. If not, the value can be used only to set the initial values. | | menuIsFloating | boolean | true | Sets if the dropdown is rendered above content or as a part of it. Useful when isMenuOpen is true. |

Fetch Options Function

The component can either be provided all options to render in props, or a function used to fetch options as necessary. This function should support:

1. Searching by string (component input). If search string is provided, options should be provided including their ancestors.
2. Paging
3. Fetching children of a node

The function is passed an object with the following attributes:

| Attribute | Type | Description | | :----------- | :------- | :---------------------------------------------------------------------------------------------------- | | searchString | string | Search string entered by the user. Possibly empty. | | optionID | string | Identifier of the option being expanded (whose children should be fetched). Possibly undefined/empty. | | limit | number | Number of options to fetch (page size). Based on fetchLimit property. | | offset | number | Fetch offset. | | option | object | Th option being expanded. Possibly undefined. |

Custom Option Renderer

You can override the built-in option renderer by specifying your own optionRenderer property. Your renderer should return a React element that represents the specified option. It will be passed the following named parameters:

| Property | Type | Description | | :---------- | :-------------- | :------------------------------------------------------------ | | data | Array<Object> | Options to render in the menu list. | | key | string | A unique identifier for each element created by the renderer. | | optionStyle | Object | Passed styles for option. | | selectProps | SelectProps | Props of Select. | | isFocused | bool | Whether the option is focused. | | isDisabled | bool | Whether the option is focused. | | isSelected | bool | Whether the option is selected. |

SelectProps

If you override the optionRenderer the react-select props are passed in the selectProps property. It gives you access to the internals of the select. Some useful properties are listed below.

| Property | Type | Description | | :------------- | :--------- | :------------------------------------------------------------------------------------------------ | | childrenKey | string | Attribute of option that contains the children key. | | key | string | A unique identifier for each element created by the renderer. | | labelKey | string | Attribute of option that contains the display text. | | getOptionLabel | Function | Function to extract label from an option. If specified, overrides labelKey. | | renderAsTree | bool | Whether the options should be render as a tree. | | searchString | string | Current content of the search input. | | onOptionSelect | Function | Callback to update the selected values; for example, you may want to call this function on click. | | onOptionToggle | Function | Expand/Collapse option if it has children. | | valueKey | string | Attribute of option that contains the value. |

IntelligentTreeSelect public API

The following methods can be called on instances of the intelligent-tree-select component (accessed via a ref).

| Method | Description | | :------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | resetOptions | Force reloading of options when fetchOptions property is used to specify how to load options. If options are specified in props, this reloads them from the current props. | | getOptions | Gets the options (flattened) currently provided by the component. | | focus | Focus the tree select input. | | blurInput | Blur the tree select input. |