Multiselect

A <select> alternative multiple values.

Overview

The <Multiselect> renders an array of data and manages the selection, filtering and value state.

<Multiselect defaultValue={["Yellow"]} data={["Red", "Yellow", "Blue", "Orange"]} />;

<Multiselect
  defaultValue={["Yellow"]}
  data={["Red", "Yellow", "Blue", "Orange"]}
/>;

Like other React Widget components, data can be complex; not limited to strings or numbers.

<Multiselect dataKey="id" textField="color" defaultValue={[1]} data={[ { id: 1, color: "Red" }, { id: 2, color: "Yellow" }, { id: 3, color: "Blue" }, { id: 4, color: "Orange" }, ]} />;

<Multiselect
  dataKey="id"
  textField="color"
  defaultValue={[1]}
  data={[
    { id: 1, color: "Red" },
    { id: 2, color: "Yellow" },
    { id: 3, color: "Blue" },
    { id: 4, color: "Orange" },
  ]}
/>;

Custom Rendering

Keyboard shortcuts

• left arrow move focus to previous tag
• right arrow move focus to next tag
• delete deselect focused tag
• backspace deselect next tag
• alt + up arrow close Multiselect
• down arrow open Multiselect, and move focus to next item
• up arrow move focus to previous item
• home move focus to first item
• end move focus to last item
• enter select focused item
• ctrl + enter create new tag from current searchTerm
• any key search list for item starting with key

API

allowCreate

Enables the list option creation UI. onFilter will only the UI when actively filtering for a list item.

type: truefalse'onFilter'

default:false

autoFocus

Pass focus to the Multiselect when it mounts.

type: boolean

busy

Controls the loading/busy spinner visibility. Presentational only! Useful for providing visual feedback while data is being loaded.

<> <Multiselect busy /> <br/> <Multiselect busy busySpinner={ <span className="fas fa-sync fa-spin" /> }/> </>

<>
  <Multiselect busy />
  <br/>
  <Multiselect busy busySpinner={
    <span className="fas fa-sync fa-spin" />
  }/>
</>

type: boolean

busySpinner

Specify the element used to render the busy indicator

type: node

clearTagIcon

Specify the element used to render tag clear icons.

type: ReactReactNode

default:times

containerClassName

Adds a css class to the input container element.

type: string

data

An array of possible values for the Multiselect.

Tip: When data is an array of objects consider specifying textField and dataKey as well.

type: array

default:[]

dataKey

A property name that provides the value of the data items. This value is used to uniquely distinigush items from others in the data list.

Generally, dataKey points to an Id field, or other unique identifier. When not provided, the referential identity of each data item is used.

let colors = [ { id: 0, name: 'orange'}, { id: 1, name: 'purple'}, { id: 2, name: 'red' }, { id: 3, name: 'blue' }, ]; let widget = ( <Multiselect data={colors} dataKey='id' textField='name' defaultValue={[1, 2]} /> ) render(widget);

let colors = [
  { id: 0, name: 'orange'},
  { id: 1, name: 'purple'},
  { id: 2, name: 'red' },
  { id: 3, name: 'blue' },
];
let widget = (
  <Multiselect
    data={colors}
    dataKey='id'
    textField='name'
    defaultValue={[1, 2]}
  />
)
render(widget);

type: string(dataItem?) => string

defaultOpen

type:

default:false

defaultSearchTerm

type:

default:''

defaultValue

type:

default:[]

disabled

let colors = ['orange', 'red', 'blue', 'purple']; <> <Multiselect disabled data={colors} defaultValue={["orange", "blue"]} /> <Multiselect data={colors} defaultValue={["orange", "blue"]} disabled={['red', 'purple']} /> </>

let colors = ['orange', 'red', 'blue', 'purple'];
<>
  <Multiselect
    disabled
    data={colors}
    defaultValue={["orange", "blue"]}
  />
  <Multiselect
    data={colors}
    defaultValue={["orange", "blue"]}
    disabled={['red', 'purple']}
  />
</>

type: booleanArray

dropUp

Controls the opening direction of the Multiselect popup.

<Multiselect dropUp data={[ 'orange', 'red', 'blue', 'purple' ]} />;

<Multiselect
  dropUp
  data={[
    'orange',
    'red',
    'blue',
    'purple'
  ]}
/>;

type: boolean

filter

Enable and customize filtering behavior for the Multiselect. Specify one of the built-in methods ("startsWith" "eq" "contains") or provide a function that returns true or false for each passed in item (analogous to the array.filter builtin)

You can explicitly disable filtering by setting filter to false.

let people = listOfPeople(); function filterLastName(person, value) { let lastname = person.lastName.toLowerCase() let search = value.toLowerCase(); return lastname.indexOf(search) === 0 } <> <Multiselect data={people} textField='fullName' filter='contains' /> <Multiselect data={people} textField='fullName' filter={filterLastName} /> </>

let people = listOfPeople();
function filterLastName(person, value) {
  let lastname = person.lastName.toLowerCase()
  let search  = value.toLowerCase();
  return lastname.indexOf(search) === 0
}
<>
  <Multiselect
    data={people}
    textField='fullName'
    filter='contains'
  />
  <Multiselect
    data={people}
    textField='fullName'
    filter={filterLastName}
  />
</>

type:

default:'startsWith'

focusFirstItem

type:

default:false

groupBy

To display grouped lists, specify a property name, or accesor function, whose value is used to group the data list.

The groupBy value is also used as the text for group headings when groupComponent is not provided.

let people = listOfPeople(); <> <Multiselect data={people} textField='fullName' groupBy='lastName' /> <Multiselect data={people} textField='fullName' groupBy={person => person.fullName.length} /> </>

let people = listOfPeople();
<>
  <Multiselect
    data={people}
    textField='fullName'
    groupBy='lastName'
  />
  <Multiselect
    data={people}
    textField='fullName'
    groupBy={person => person.fullName.length}
  />
</>

type: string(dataItem?) => string

handleOpen

type: function

inputProps

An object of props that is passed directly to the underlying input component.

type: Object

listComponent

type:

default:List

listProps

An object of props that is passed directly to the underlying List component.

type: Object

messages

Object hash containing display text and/or text for screen readers. Use the messages object to localize widget text or provide custom rendering.

type:

onChange

A callback fired when the current value changes.

let colors = ['Orange', 'Red', 'Blue', 'Purple']; function Example() { const [value, setValue] = useState(['orange', 'red']) return ( <Multiselect data={colors} value={value} onChange={value => setValue(value)} /> ) } <Example/>;

let colors = ['Orange', 'Red', 'Blue', 'Purple'];
function Example() {
  const [value, setValue] = useState(['orange', 'red'])
  return (
    <Multiselect
      data={colors}
      value={value}
      onChange={value => setValue(value)}
    />
  )
}
<Example/>;

type: {function ( dataItems: ?any[], metadata: { dataItem: any, action: 'insert' | 'remove', originalEvent: SyntheticEvent, lastValue: ?any[], searchTerm: ?string } ): void}

onCreate

This handler fires when the user chooses to create a new list option. It is up to the widget parent to implement creation logic, a common implementation is shown below, where the new tag is selected and added to the data list.

const initialList = listOfPeople(); function MultiselectWithCreate() { const [value, setValue] = useState([]); const [people, setPeople] = useState(initialList); function handleCreate(name) { let newOption = { name, id: people.length + 1 } // select new option setValue([...value, newOption]); // add new option to our dataset setPeople(data => [newOption, ...data]) } return ( <Multiselect data={people} value={value} textField="fullName" allowCreate="onFilter" onCreate={handleCreate} onChange={setValue} /> ) }

const initialList = listOfPeople();
function MultiselectWithCreate() {
  const [value, setValue] = useState([]);
  const [people, setPeople] = useState(initialList);
  function handleCreate(name) {
    let newOption = { name, id: people.length + 1 }
    // select new option
    setValue([...value, newOption]);
    // add new option to our dataset
    setPeople(data => [newOption, ...data])
  }
  return (
    <Multiselect
      
      data={people}
      value={value}
      textField="fullName"
      allowCreate="onFilter"
      onCreate={handleCreate}
      onChange={setValue}
    />
  )
}

type: { (searchTerm: string) => void }

onSearch

A callback fired when the current searchTerm changes.

type: {function ( searchTerm: ?string, metadata: { action: 'clear' | 'input', lastSearchTerm: ?string, originalEvent: SyntheticEvent, } ): void}

onSelect

This handler fires when an item has been selected from the list. It fires before the onChange handler and fires regardless of whether the value has actually changed.

let alertWhenSelected = () => alert('selected!'); let alertWhenChanged = () => alert('changed!'); <Multiselect onSelect={alertWhenSelected} onChange={alertWhenChanged} data={['Orange', 'Red', 'Blue', 'Purple']} />

let alertWhenSelected = () => alert('selected!');
let alertWhenChanged = () => alert('changed!');
<Multiselect
  onSelect={alertWhenSelected}
  onChange={alertWhenChanged}
  data={['Orange', 'Red', 'Blue', 'Purple']}
/>

type: { (dataItem: ?any, metadata: { originalEvent: SyntheticEvent }) => void }

open

Controls the visibility of the Multiselect popup. Use defaultOpen to set an initial value for uncontrolled widgets.

let colors = ['Orange', 'Red', 'Blue', 'Purple']; function Example() { const [open, setOpen] = useState(false) return ( <div> <button onClick={() => setOpen(prev => !prev)}> {open ? 'close' : 'open'} </button> <Multiselect open={open} data={colors} /> </div> ) }; <Example/>

let colors = ['Orange', 'Red', 'Blue', 'Purple'];
function Example() {
  const [open, setOpen] = useState(false)
  return (
    <div>
      <button onClick={() => setOpen(prev => !prev)}>
        {open ? 'close' : 'open'}
      </button>
      <Multiselect
        open={open}
        data={colors}
      />
    </div>
  )
};
<Example/>

type: boolean

placeholder

Text to display in the input when the value is empty.

type: string

popupComponent

type:

default:BasePopup

popupTransition

A Transition component from react-transition-group. The provided component will be used instead of the default SlideDownTransition for fully customizable animations. The transition component is also injected with a dropUp prop indicating the direction it should open.

type: elementType

readOnly

Controls the read-only state of the Multiselect.

let colors = ['orange', 'red', 'blue', 'purple']; <Multiselect readOnly data={colors} defaultValue={["orange", "blue"]} />

let colors = ['orange', 'red', 'blue', 'purple'];
<Multiselect
  readOnly
  data={colors}
  defaultValue={["orange", "blue"]}
/>

type: boolean

renderListGroup

Customize the rendering of the group headings when groupBy is active.

let people = listOfPeople(); <Multiselect data={people} textField='fullName' groupBy={person => person.fullName.length} renderListGroup={ ({ group }) => ( <span>{group + ' letters long'}</span> )} />

let people = listOfPeople();
<Multiselect
  data={people}
  textField='fullName'
  groupBy={person => person.fullName.length}
  renderListGroup={ ({ group }) => (
    <span>{group + ' letters long'}</span>
  )}
/>

type: function

renderListItem

Customize the rendering of each Multiselect list item.

let people = listOfPeople(); <Multiselect data={people} textField='fullName' renderListItem={({ item }) => ( <span> <strong>{item.firstName}</strong> {" " + item.lastName} </span> )} />

let people = listOfPeople();
<Multiselect
  data={people}
  textField='fullName'
  renderListItem={({ item }) => (
    <span>
      <strong>{item.firstName}</strong>
      {" " + item.lastName}
    </span>
  )}
/>

type: function

renderTagValue

type: RenderTagProp<TDataItem>

searchTerm

Controls the value of the search text used to filter undefined items. searchTerm is only applicable when filtering is enabled.

Use defaultSearchTerm instead to set an initial value for uncontrolled widgets.

type: string

selectIcon

Specify the element used to render the select (down arrow) icon.

type: node

showPlaceholderWithValues

Continue to show the input placeholder even if tags are selected

type: boolean

default:false

showSelectedItemsInList

Continue to show the selected items in the dropdown list

type: boolean

default:false

tagListComponent

type: ReactComponentType<MultiselectTagListProps<DataItem>>

default:<MultiselectTagList>

tagOptionComponent

type: TagComponentProp

textField

A property name, or accessor function, that provides the text content of the data items. The Multiselect will filter data based on this value as well as use it as the default display value for list items and selected values.

let people = listOfPeople(); let widgets = ( <div className='w-64'> <Multiselect textField='firstName' defaultValue={people.slice(0,2)} data={people} /> <Multiselect textField={item => item.firstName + ' ' + item.lastName} defaultValue={people.slice(0,2)} data={people} /> </div> ) render(widgets);

let people = listOfPeople();
let widgets = (
  <div className='w-64'>
    <Multiselect
      textField='firstName'
      defaultValue={people.slice(0,2)}
      data={people}
    />
    <Multiselect
      textField={item => item.firstName + ' ' + item.lastName}
      defaultValue={people.slice(0,2)}
      data={people}
    />
  </div>
)
render(widgets);

type: string(dataItem?) => string

value

Controls the current value of the Multiselect.

let widget = ( <Multiselect defaultValue={["orange", "red"]} data={[ 'orange', 'red', 'blue', 'purple' ]} /> ); render(widget);

let widget = (
  <Multiselect
    defaultValue={["orange", "red"]}
    data={[
      'orange',
      'red',
      'blue',
      'purple'
    ]}
  />
);
render(widget);

type: array