Picky ☜
Yet another React select list.
Motivation
When dealing with medium+ length select lists, especially multi-select lists. The common approach is to use tags e.g.
Source: React-Select by Jed Watson
This approach is fine for smaller lists. When you have options for 20, 30, 100+ options that the use can select, it becomes unmanigable.
For example you have a internal staff mailing list. You want to mail all staff in a department (30 employees). You select all. That would be 30 tags taking unneccessary space.
This is a multiselect with checkboxes, a select all option, and a filter. Along a similar vein as David Stutz's Bootstrap Multiselect. There is a port of that library to react with Skratchdot's React Bootstrap Multiselect. However I don't want a dependency on jQuery. If you are already using jQuery that might be an alternative for you.
If you like the tag list like React-Select, then that would be a great option for you. It's a really great, well-tested library. Give it a look.
You can also achieve the same result with a great deal of flexibility using Paypal's Downshift.
More on React Select
React Select V2 is pretty incredible, you can replace and provide custom functionality for almost every element of the select component. With a little work you could rebuild Picky from the components of React Select, take a look at React Select: Experimental, the Popout example is close to what Picky does. You could even build a date picker in React Select...HOW COOL IS THAT!
What Picky is
Picky provides a medium amount of flexibility, you can custom render: Options, List (useful for creating a virtualized menu), and SelectAll. Any further customisation and it's a little out of scope for Picky. It was built with a common pattern in mind so you can get up and running with little-to-no work. If you need Picky to be more flexible, I'm happy to take a PR if it would benefit the rest of the community.
Peer Dependencies
"react": "^16.8.0",
"react-dom": "^16.8.0"
Installation
npm install --save react-picky
# or
yarn add react-picky
Screenshots
Single Select
Multi Select
Usage
Basic example
;; // Include CSS <Picky id="picky" options=1 2 3 4 5 value= multiple=true includeSelectAll=true includeFilter=true onChange= console dropdownHeight=600/>;
Examples
Props
PickydefaultProps = numberDisplayed: 3 options: filterDebounce: 150 dropdownHeight: 300 {} tabIndex: 0 keepOpen: true selectAllText: 'Select all' selectAllMode: 'default';PickypropTypes = id: PropTypesstringisRequired placeholder: PropTypesstring value: PropTypes numberDisplayed: PropTypesnumber multiple: PropTypesbool options: PropTypesarrayisRequired onChange: PropTypesfuncisRequired open: PropTypesbool includeSelectAll: PropTypesbool includeFilter: PropTypesbool filterDebounce: PropTypesnumber dropdownHeight: PropTypesnumber onFiltered: PropTypesfunc onOpen: PropTypesfunc onClose: PropTypesfunc valueKey: PropTypesstring labelKey: PropTypesstring render: PropTypesfunc tabIndex: PropTypes keepOpen: PropTypesbool manySelectedPlaceholder: PropTypesstring allSelectedPlaceholder: PropTypesstring selectAllText: PropTypesstring renderSelectAll: PropTypesfunc defaultFocusFilter: PropTypesbool className: PropTypesstring renderList: PropTypesfunc filterPlaceholder: PropTypesstring disabled: PropTypesbool getFilterValue: PropTypesfunc caseSensitiveFilter: PropTypesbool buttonProps: PropTypesobject selectAllMode: PropTypes clearFilterOnClose: PropTypesbool singleSelectPlaceholder: PropTypesfunc;
Prop descriptions
id
- HTML id assigned to input. Also used as a base for other elements inside Picky.placeholder
- Default message when no items are selected.value
- The selected value(s), array if multiple is true. Not needed if using as an uncontolled componentnumberDisplayed
- Then number of selected options displayed until it turns into '(selected count) selected'.multiple
- Set to true for a multiselect, defaults to false.options
- Array of possible options.onChange
- Called whenever selected value(s) have changed. Pass the selected value back intovalue
.open
- Can open or close the dropdown manually. Defaults to false.includeSelectAll
- If set totrue
will add aSelect All
checkbox at the top of the list.includeFilter
- If set totrue
will add an input at the top of the dropdown for filtering the results.filterDebounce
- Debounce timeout, used to limit the rate the internalonFilterChange
gets called. Defaults to 150ms.dropdownHeight
- The height of the dropdown. Defaults to 300px.onFiltered
- Called after a filter has been done with the filtered options.onOpen
- Called after the dropdown has opened.onClose
- Called after the dropdown has closed.valueKey
- If supplying an array of objects as options, this is required. It's used to identify which property on the object is the value.labelKey
- If supplying an array of objects as options, this is required. It's used to identify which property on the object is the label.render
- Used for custom rendering of items in the dropdown. More info below.tabIndex
- Pass tabIndex to component for accessibility. Defaults to 0keepOpen
- Default true. Single selects close automatically when selecting a value unless this is set to true.manySelectedPlaceholder
- Default "%s selected" where %s is the number of items selected. This gets used when the number if items selected is more than thenumberDisplayed
prop and when all options are not selected.allSelectedPlaceholder
- Default "%s selected" where %s is the number of items selected. This gets used when all options are selected.selectAllText
- Default "Select all", use this to override "Select all" text from top of dropdown when included withincludeSelectAll
.renderSelectAll
- Used for rendering a custom select alldefaultFocusFilter
- If set to true, will focus the filter by default when opened.renderList
- Render prop for whole list, you can use this to add virtualization/windowing if necessaryfilterPlaceholder
- Override the filter placeholder. Defaults to 'Filter...'getFilterValue
- Will provide the input value of filter to the picky dropdown, so that if we have a larger list of options then we can only supply the matching options based on this value.caseSensitiveFilter
- If true options will be returned when they match casebuttonProps
- Additional props to apply the the button component, useful for supplying class names.selectAllMode
- default:default
. When the mode isfiltered
the Select All won't be hidden when filtering.clearFilterOnClose
- When set to true filtered options and filtered state will be cleared on close. Defaults to false.filterTermProcessor
- A function that takes a string and returns a string. Useful for trimming and processing a filter term before it filters the options. Default: (term) => termsingleSelectPlaceholder
- A function that takes the currently selected value and returns a string.(val: OptionType) => string
Custom rendering
Items
You can render out custom items for the dropdown.
Example
<Picky id="picky" value=thisstatearrayValue options=bigList onChange=thisselectMultipleOption open=false valueKey="id" labelKey="name" multiple=true includeSelectAll=true includeFilter=true getFilterValue=thisgetFilterValue dropdownHeight=600 render= style isSelected item selectValue labelKey valueKey multiple return <li style=style // required className=isSelected ? 'selected' : '' // required to indicate is selected key=itemvalueKey // required onClick= > /* required to select item */ <input type="checkbox" checked=isSelected readOnly /> <span style= fontSize: '30px' >itemlabelKey</span> </li> ; />
The render callback gets called with the following properties: style, isSelected, item, labelKey, valueKey, selectValue, multiple
isSelected
- boolean - true if item is selected. Use this for styling accordingly.item
- object | number | string - The item to render.labelKey
- Used to get the label if item is an objectvalueKey
- Used to get the value if item is an object, good for keys.selectValue
- function(item) - Selects the item on clickmultiple
- boolean - Indicates if is a multiselect.
Note
- If your rendered item affects the height of the item in anyway. Supply
itemHeight
to Picky. - If you wish to show a radio button or a checkbox, be sure to add
readOnly
prop to the input.
Select All
<Picky // ... renderSelectAll= filtered tabIndex allSelected toggleSelectAll multiple // Don't show if single select or items have been filtered. if multiple && !filtered return <div tabIndex=tabIndex role="option" className=allSelected ? 'option selected' : 'option' onClick=toggleSelectAll onKeyPress=toggleSelectAll > <h1>SELECT ALL</h1> </div> ; />
Gets called with the following properties:
filtered
: boolean - true if items have been filtered.allSelected
: boolean true if all items are selected.toggleSelectAll
: function selects or deselects all items.tabIndex
: number used for specifying tab index.multiple
: boolean true if multiselect.
Render List
<Picky id="picky" value=thisstatearrayValue options=bigList onChange=thisselectMultipleOption open=true valueKey="id" labelKey="name" multiple=true includeSelectAll=true includeFilter=true dropdownHeight=600 manySelectedPlaceholder=dynamicPlaceholder defaultFocusFilter=true renderList= items />
This is an example of a custom rendered list.
styled-components support
Support is pretty basic by allowing a className
prop to <Picky>
, so as a side effect you can add a custom class to the core Picky for easier style overrides.
Usage
const Select = ` background-color: #ff0000; .picky__dropdown, .option { font-size: 2em; }`;
Migrations
v4 to v5
Picky is no longer a default export
V4
import Picky from 'react-picky'
V5
import { Picky } from 'react-picky'