Listbox

A <Listbox> represents a list of selectable options. Single or multiple options can be selected based on the situation.

Overview

The <Listbox> component is visually similar to the native <select> element with a size attribute provided. Like the native element, it can be used to select a single option from a list or multiple.

For single options, selection follows the <select> behavior of not allowing deselection once an item is chosen, only switching to another item.

import Listbox from "react-widgets/Listbox"; <Listbox defaultValue={["Yellow", "Orange"]} data={["Red", "Yellow", "Blue", "Orange"]} />;

import Listbox from "react-widgets/Listbox";
<Listbox
  defaultValue={["Yellow", "Orange"]}
  data={["Red", "Yellow", "Blue", "Orange"]}
/>;

Multiple selections

Add the multiple prop to allow toggling more than one item. In multiselect mode items default to toggling their selected state on click, or keyboard selection. Selected values are represented as an Array.

import Listbox from "react-widgets/Listbox"; <Listbox multiple defaultValue={["Yellow", "Orange"]} data={["Red", "Yellow", "Blue", "Orange"]} />;

import Listbox from "react-widgets/Listbox";
<Listbox
  multiple
  defaultValue={["Yellow", "Orange"]}
  data={["Red", "Yellow", "Blue", "Orange"]}
/>;

Complex data

Like the dropdown components the <Listbox> can accept complex data items. Configure dataKey and textField to resolve values and display text to the correct places.

const [value, setValue] = useState(1); return ( <> <p> Current Value: <strong>{value}</strong> </p> <Listbox dataKey="id" textField="color" value={value} onChange={(nextValue) => setValue(nextValue.id)} data={[ { id: 1, color: "Red" }, { id: 2, color: "Yellow" }, { id: 3, color: "Blue" }, ]} /> </> );

const [value, setValue] = useState(1);
return (
  <>
    <p>
      Current Value: <strong>{value}</strong>
    </p>
    <Listbox
      dataKey="id"
      textField="color"
      value={value}
      onChange={(nextValue) => setValue(nextValue.id)}
      data={[
        { id: 1, color: "Red" },
        { id: 2, color: "Yellow" },
        { id: 3, color: "Blue" },
      ]}
    />
  </>
);

API

data

An array of possible values for the Listbox.

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

type: array

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 = ( <Listbox 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 = (
  <Listbox
    data={colors}
    dataKey='id'
    textField='name'
    defaultValue={[1, 2]}
  />
)
render(widget);

type: string(dataItem?) => string

disabled

type: booleanArray

focusedItem

type: any

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:

onHoverOption

type: function

onMove

type: function

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!'); <Listbox onSelect={alertWhenSelected} onChange={alertWhenChanged} data={['Orange', 'Red', 'Blue', 'Purple']} />

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

type: function

optionComponent

type: elementType

renderGroup

type: function

renderItem

type: function

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

selectedItem

type: any

textField

A property name, or accessor function, that provides the text content of the data items. The Listbox 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'> <Listbox textField='firstName' defaultValue={people.slice(0,2)} data={people} /> <Listbox 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'>
    <Listbox
      textField='firstName'
      defaultValue={people.slice(0,2)}
      data={people}
    />
    <Listbox
      textField={item => item.firstName + ' ' + item.lastName}
      defaultValue={people.slice(0,2)}
      data={people}
    />
  </div>
)
render(widgets);

type: string(dataItem?) => string