Skip to content

Files

Latest commit

 

History

History
123 lines (96 loc) · 14.4 KB

README.md

File metadata and controls

123 lines (96 loc) · 14.4 KB

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