DropdownList

A <select> element alternative for single value lists, with filtering. The <DropdownList> renders an array of data and manages the selection, filtering and value state.

import DropdownList from "react-widgets/DropdownList";

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

Keyboard Shortcuts#

DropdownList 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#

allowCreate#

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

type: truefalse'onFilter'

default:false

autoComplete#

type: 'on''off'

autoFocus#

Pass focus to the DropdownList when it mounts.

type: boolean

busy#

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

<>
  <DropdownList busy />
  <br/>
  <DropdownList busy busySpinner={
    <span className="fas fa-sync fa-spin" />
  }/>
</><>
  <DropdownList busy />
  <br/>
  <DropdownList 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 DropdownList.

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

type: string(dataItem?) => string

defaultOpen#

type:

default:false

defaultSearchTerm#

type:

default:''

delay#

type:

default:500

disabled#

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


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

type: booleanArray

dropUp#

Controls the opening direction of the DropdownList popup.

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

type: boolean

filter#

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

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

type:

default:true

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

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

type: string(dataItem?) => string

inputProps#

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

type: Object

listComponent#

type: ReactComponentstring

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 (
    <DropdownList
      data={colors}
      value={value}
      onChange={value => setValue(value)}
    />
  )
}

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

type: {function ( dataItems: ?any, metadata: { lastValue: ?any, searchTerm: ?string originalEvent: SyntheticEvent, } ): 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 DropdownListWithCreate() {
  const [value, setValue] = useState(null);
  const [people, setPeople] = useState(initialList);

  function handleCreate(name) {
    let newOption = { name, id: people.length + 1 }

    // select new option
    setValue(newOption);

    // add new option to our dataset
    setPeople(data => [newOption, ...data])
  }

  return (
    <DropdownList
      filter
      data={people}
      value={value}
      textField="fullName"
      allowCreate="onFilter"
      onCreate={handleCreate}
      onChange={setValue}
    />
  )
}const initialList = listOfPeople();
function DropdownListWithCreate() {
  const [value, setValue] = useState(null);
  const [people, setPeople] = useState(initialList);
  function handleCreate(name) {
    let newOption = { name, id: people.length + 1 }
    // select new option
    setValue(newOption);
    // add new option to our dataset
    setPeople(data => [newOption, ...data])
  }
  return (
    <DropdownList
      filter
      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, lastSearchTerm, originalEvent? })

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

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

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

onToggle#

A callback fired with the DropdownList'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 DropdownList 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>
      <DropdownList
        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>
      <DropdownList
        open={open}
        data={colors}
      />
    </div>
  )
};
<Example/>

type: boolean

optionComponent#

type: ReactComponentstring

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: ReactComponentstring

readOnly#

Controls the read-only state of the DropdownList.

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


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

type: boolean

renderListGroup#

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

let people = listOfPeople();

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

type: function

renderListItem#

Customize the rendering of each DropdownList list item.

let people = listOfPeople();

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

type: function

renderPopup#

type: function

renderValue#

A React render prop for customizing the rendering of the DropdownList value

let people = listOfPeople();

<DropdownList
  data={people}
  textField='fullName'
  renderValue={({ item }) => (
    <span>
      <strong>hi,</strong>{' ' + item.fullName}
    </span>
  )}
  defaultValue={people[0]}
/>let people = listOfPeople();
<DropdownList
  data={people}
  textField='fullName'
  renderValue={({ item }) => (
    <span>
      <strong>hi,</strong>{' ' + item.fullName}
    </span>
  )}
  defaultValue={people[0]}
/>

type: RenderValueProp<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

default:caretDown

textField#

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

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

type: string(dataItem?) => string

value#

Controls the current value of the DropdownList.

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

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

type: any