Combobox

Also called an autocomplete or autosuggest component. A "combobox" is a plain text input that can provide a list of suggestions. The <Combobox> allows any text value but also provides a list of auto complete options to select from.

import Combobox from "react-widgets/Combobox";

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

Textbox with suggestions#

Mix and match props like hideCaret and hideEmptyPopup props to create a traditional autocomplete look.

<Combobox
  hideCaret
  hideEmptyPopup
  data={["Red", "Yellow", "Blue", "Orange"]}
  placeholder="Search for a color"
/><Combobox
  hideCaret
  hideEmptyPopup
  data={["Red", "Yellow", "Blue", "Orange"]}
  placeholder="Search for a color"
/>

Keyboard Shortcuts#

Combobox implements many keyboard shortcuts for power or keyboard only users.

alt + down arrow

open dropdown

alt + up arrow

close dropdown

down arrow

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 option from current searchTerm

any key

search list for item starting with key

API#

autoFocus#

Pass focus to the Combobox when it mounts.

type: boolean

autoSelectMatches#

If a data item matches the current typed value select it automatically.

type: boolean

busy#

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

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

type: boolean

busySpinner#

Specify the element used to render the busy indicator

type: node

containerClassName#

Adds a css class to the input container element.

type: string

data#

An array of possible values for the Combobox.

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 = (
  <Combobox
    data={colors}
    dataKey='id'
    textField='name'
    defaultValue={1}
  />
)

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

type: string(dataItem?) => string

defaultOpen#

type:

default:false

defaultValue#

type:

default:''

disabled#

let colors = ['orange', 'red', 'blue', 'purple'];


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

type: booleanArray

dropUp#

Controls the opening direction of the Combobox popup.

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

type: boolean

filter#

Enable and customize filtering behavior for the Combobox. 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
}

<>
  <Combobox
    data={people}
    textField='fullName'
    filter='contains'
  />
  <Combobox
    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
}
<>
  <Combobox
    data={people}
    textField='fullName'
    filter='contains'
  />
  <Combobox
    data={people}
    textField='fullName'
    filter={filterLastName}
  />
</>

type:

default:true

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();

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

type: string(dataItem?) => string

hideCaret#

Hide the combobox dropdown indicator.

<>
  <Combobox hideCaret />
  <br/>
  <Combobox busy hideCaret />
</><>
  <Combobox hideCaret />
  <br/>
  <Combobox busy hideCaret />
</>

type: boolean

hideEmptyPopup#

Do not show the auto complete list when it returns no results.

type: boolean

inputProps#

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

type: Object

listComponent#

type: elementType

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:

name#

The HTML name attribute, passed directly to the input element.

type: string

onChange#

A callback fired when the current value changes.

let colors = ['Orange', 'Red', 'Blue', 'Purple'];

function Example() {
  const [value, setValue] = useState('orange')

  return (
    <Combobox
      data={colors}
      value={value}
      onChange={value => setValue(value)}
    />
  )
}

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

type: ChangeHandler<TDataItemstring>

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!');

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

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

onToggle#

A callback fired with the Combobox's popup visibility is about to change.

Use in conjunction with the open prop to manually control the popup visibility.

type: function

open#

Controls the visibility of the Combobox 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>
      <Combobox
        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>
      <Combobox
        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 Combobox.

let colors = ['orange', 'red', 'blue', 'purple'];


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

type: boolean

renderListGroup#

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

let people = listOfPeople();

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

type: function

renderListItem#

Customize the rendering of each Combobox list item.

let people = listOfPeople();

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

type: function

selectIcon#

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

type: node

default:caretDown

textField#

A property name, or accessor function, that provides the text content of the data items. The Combobox 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'>
    <Combobox
      textField='firstName'
      defaultValue={people[0]}
      data={people}
    />
    <Combobox
      textField={item => typeof item === 'string' ? item : item.firstName + ' ' + item.lastName}
      defaultValue={people[0]}
      data={people}
    />
  </div>
)

render(widgets);let people = listOfPeople();
let widgets = (
  <div className='w-64'>
    <Combobox
      textField='firstName'
      defaultValue={people[0]}
      data={people}
    />
    <Combobox
      textField={item => typeof item === 'string' ? item : item.firstName + ' ' + item.lastName}
      defaultValue={people[0]}
      data={people}
    />
  </div>
)
render(widgets);

type: string(dataItem?) => string

value#

Controls the current value of the Combobox.

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

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

type: any