ComboBox - Getting started
Zippytech React Toolkit is distributed via npm. So getting it installed is as easy as:
$ npm install @zippytech/react-toolkit --save
Or, if you are using yarn you have to run:
$ yarn add @zippytech/react-toolkit
To start using the <ComboBox /> component, all you need to import is React, the code and the styles of the component itself: @zippytech/react-toolkit/ComboBox and @zippytech/react-toolkit/ComboBox/index.css.
This is the most basic setup for a <ComboBox />. In the following sections we'll explore how to use the <ComboBox /> in various scenarios, supported props, theming, using a local/remote dataSource, etc.
The dataSource should be an array of objects. By default, each object in the dataSource should have an id property and a label property. See idProperty and displayProperty for more details.
By default, the <ComboBox /> does not collapse the list when a value is selected. Specify collapseOnSelect=true to collapse the list on selection. Using collapseOnSelectWithEnter=true and collapseOnSelect=false will only collapse the list when the user hits Enter to select a list item (but won't collapse on selection via mouse click).
Vey often you want to constrain the combo list overlay to a certain area or HTMLElement - you can do that using the constrainTo prop, as shown below:
The constrainTo can be a String CSS selector, an HTMLElement or a Function that is called with the DOM node of the ComboBox as the first argument.
When a String CSS selector is specified, the list is constrained to the first matching parent.
The <ComboBox /> list is smartly positioned to the top or to the bottom depending on the constrain region and the available space.
One of the main features of the <ComboBox /> is the ability to select multiple values. For this, it's enough to configure the <ComboBox /> with multiple=true.
See Multiselect page for more details on using multiple selection.
The <ComboBox /> can be configured to behave like an autocomplete input. See the example below and the Autocomplete page for more details.
The <ComboBox /> can be configured to behave like a dropdown (very similar to the html select element). See the example below and the Dropdown page for more details.
In the example below, you can see the dropdown behaviour, combined with a few other options.
To configure the <ComboBox /> with remote data, specify dataSource to be a Promise or a function returning a Promise.
lazyDataSource allows the remote dataSource, to be loaded lazily, so make sure you have a look at the Remote data source page for more details.
There are a lot more props supported by the <ComboBox />, but the most important scenarios have been shown above. See the example below to configure other props you might find useful.
When filtering, you can control at what point the <ComboBox /> should start filtering values using filterMinLength - this specifies the minimum length of the text when filtering values inside the <ComboBox /> list. filterMinLength defaults to 0.