material-multi-picker

Typeahead multipicker component, uses React 16, Material-UI 3 or 4, and downshift.

This component allows users to pick multiple items from a typeahead dropdown. It's easy to use straight out-of-the-box, but allows visual customisation while remaining within the Material Design universe.

Check out the live demos in the documentation.

Features

• Functional and aesthetic with minimal configuration
• Typeahead suggestions can be provided synchronously or asynchronously
• Good keyboard and screenreader accessibility (due to being build on PayPal's downshift primitive)
• Handles most errors and edge cases gracefully
• Conforms to Material Design guidelines (due to using components from the Material UI library)
• Key visual aspects are customisable

Usage

Install with npm install material-multi-picker or yarn add material-multi-picker. Make sure you have React (16+) and Material UI (3+) installed!

import MultiPicker from 'material-multi-picker';
import React, { useState } from 'react';
 
const favoriteThings = [
    "raindrops on roses",
    "whiskers on kittens",
    "bright copper kettles",
    "warm woolen mittens"
]
 
function getSuggestions(inputValue) {
    return favoriteThings.filter(
        thing => thing.includes(inputValue.toLowerCase())
    );
}
 
function FavouriteThingPicker() {
    //use React hooks for state (React 16.8+ only)
    const  [myThings, setMyThings ] = useState([]);
 
    return (
        <MultiPicker
            value={ myThings }
            onChange={ setMyThings }
            getSuggestedItems={ getSuggestions }
            itemToString={ item => item }
        />
    );
}

Props

Note that the picker can only be used as a Controlled Component.

Prop name	Type	Required?	Description
value	array	yes	The items currently displayed as "selected" in the picker. They will appear as a series of Chips.
onChange	function(newValue)	yes	Callback fired by the component when the user changes the selected items.
getSuggestedItems	function(inputValue, selectedItems)	yes	Used by the picker to get the suggestions that will appear in the dropdown. Return an array of items, a promise that resolves to an array of items, or the special NOT_ENOUGH_CHARACTERS symbol (see below).
itemToString	function(item)	yes	Used by the picker to extract a unique identifer string for an item (must return a string).
name	string	no	If set, the same name will be applied to the input field
disabled	boolean	no	If true, prevents all interaction with the component (chip popovers will still appear if configured)
error	boolean	no	If true, the picker will display in an errored state (using theme colors)
required	boolean	no	If true, the picker will indicate that the value is required
variant	'standard', 'filled', or 'outlined'	no	Sets the display style of the field (as with the Material UI text field). Defaults to 'standard'.
maxDropdownHeight	number	no	Maximum height of the dropdown element (in pixels). If there are too many suggestions, the dropdown will become scrollable. Defaults to unlimited height.
itemToLabel	function(item)	no	Used by the picker to populate the chip labels. If not supplied, the results of itemToString will be used.
itemToAvatar	function(item)	no	Used by the picker to add material <Avatar /> icons into the chips. If not supplied, chips will have no icon.
itemToPopover	function(item)	no	Used by the picker to add material Popovers to chips, activated on hover. If not supplied, chips will have no popover.
chipColor	'primary', 'secondary' or 'default'	no	Which theme color to use for the chips. By default this is undefined, which in most themes will lead to chips being light grey.
fullWidth	boolean	no	As in Material UI, determines whether the picker will grow to fill available horizontal space. Defaults to false
autoFocus	boolean	no	As in Material UI, when true this causes the picker to get the focus when it mounts. Defaults to false
showDropdownOnFocus	boolean	no	When true, causes the picker to show the suggestions dropdown whenever the picker gets the focus, even if the user has not typed anything. Defaults to false.
label	string	no	The label applied to the input field. Defaults to "".
helperText	string	no	The helper text applied to the field (rendered below the picker). Defaults to "".
fetchDelay	number	no	The delay between the last keypress and the picker fetching suggestions. Useful to avoid spamming a service! Defaults to 0.
SuggestionComponent	React component	no	Custom component used to render suggestions in the picker dropdown (see below for a list of supplied props). Defaults to the result of itemToString.
ErrorComponent	React component	no	Custom component used to indicate a loading error in the picker dropdown (see below for a list of supplied props). Default just shows a generic error message.
useGlobalCache	string	no	If set, this causes the picker to use a global in-memory suggestions cache with the given ID, improving performance across multiple instances
clearInputOnBlur	boolean	no	Default to false. If set to true, the typeahead input will be cleared whenever the picker loses the focus. This can be useful to avoid confusing users who move on from the picker without selecting anything from the dropdown.
disablePortals	boolean	no	Defaults to false. If set to true, the dropdown will be rendered inline in the DOM instead of using <body> as the parent (can be useful for testing or limiting CSS scope)

Requiring a minimum number of characters in the input

Sometimes you may want to wait for the user to enter several characters before doing a suggestions lookup - this can reduce load on APIs and avoids bringing back unhelpful results. You can do this just by testing the length of the input in your getSuggestedItems() function and returning an empty array, but this doesn't tell the users that they need to enter more characters. Instead, return the special NOT_ENOUGH_CHARACTERS symbol, and a dropdown message will be displayed to users explaining that they need to type more characters.

import { NOT_ENOUGH_CHARACTERS } from 'material-multi-picker';

Customising suggestions in the dropdown

The default suggestion component just displays the id of the item (extracted with itemToString()) in a plain format. You can supply a React component as the SuggestionComponent prop, which will have access to the following props:

Prop name	Type	Description
itemId	string	The unique ID of the item (from itemToString)
item	any	The suggestion generated by your getSuggestedItems function
isHighlighted	boolean	true if the user is currently highlighting this suggestion (either with keyboard navigation, or by hovering over with the mouse)
inputValue	string	The string currently entered in the text input field. Useful for highlighting portions of text to indicate matches.

It's a good idea to avoid interactive or clickable elements in your component, as they may interfere with the picker's event handling.

Handling errors

If your getSuggestedItems() function throws an error, or if it returns a Promise that fails, the picker will show an Error dropdown. You can override the default appearance and behaviour of this dropdown using the ErrorComponent. Your custom ErrorComponent, you will have access to the following props:

Prop name	Type	Description
error	Error	The error encountered while loading suggestions
inputValue	string	The search string entered by the user

Migration

1.x => 2.x

• Make sure you're using React 16.8 or better (both react and react-dom)