ListBox

ListBox is used to select one or more values from a list of items.


import { ListBox } from 'primereact/listbox';
         

Listbox is used as a controlled component with value and onChange properties along with the options collection. There are two alternatives of how to define the options property; One way is providing a collection of SelectItem instances having label-value pairs whereas other way is providing an array of arbitrary objects along with the optionLabel and optionValue properties to specify the label/value field pair. In addition, options can be simple primitive values such as a string array, in this case no optionLabel or optionValue is necessary.

  • New York
  • Rome
  • London
  • Istanbul
  • Paris

<ListBox value={selectedCity} options={cities} onChange={(e: ListBoxChangeParams) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
         

  • New York
  • Rome
  • London
  • Istanbul
  • Paris

<ListBox multiple value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
         

Property name or getter function to use as the label of an option group.

  • Germany
  • Berlin
  • Frankfurt
  • Hamburg
  • Munich
  • USA
  • Chicago
  • Los Angeles
  • New York
  • San Francisco
  • Japan
  • Kyoto
  • Osaka
  • Tokyo
  • Yokohama

<ListBox value={selectedGroupedCity} options={groupedCities} onChange={(e) => setSelectedGroupedCity(e.value)} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" optionGroupTemplate={groupedItemTemplate} style={{ width: '15rem' }} listStyle={{ maxHeight: '250px' }}/>
         

  • New York
  • Rome
  • London
  • Istanbul
  • Paris

<ListBox filter value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
         

  • Australia
    Australia
  • Brazil
    Brazil
  • China
    China
  • Egypt
    Egypt
  • France
    France
  • Germany
    Germany
  • India
    India
  • Japan
    Japan
  • Spain
    Spain
  • United States
    United States

<ListBox value={selectedCountries} options={countries} onChange={(e) => setSelectedCountries(e.value)} optionLabel="name" itemTemplate={countryTemplate} style={{ width: '15rem' }} listStyle={{ maxHeight: '250px' }} />
         

  • New York
  • Rome
  • London
  • Istanbul
  • Paris

<ListBox className='p-invalid' value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
         

  • New York
  • Rome
  • London
  • Istanbul
  • Paris

<ListBox disabled value={selectedCity} options={cities} onChange={(e) => setSelectedCity(e.value)} optionLabel="name" style={{ width: '15rem' }} />
         

Whether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.

    
    <ListBox value={selectedItem} options={items} virtualScrollerOptions={{ itemSize: 38 }} onChange={(e) => setSelectedItem(e.value)} style={{ width: '15rem' }} listStyle={{ height: '250px' }}/>
             
    Compatibility with popular React form libraries.

    Formik is a popular library for handling forms in React.

    • New York
    • Rome
    • London
    • Istanbul
    • Paris
     
    
    <Toast ref={toast} />
    <ListBox
        id="item"
        name="item"
        value={formik.values.item}
        options={cities}
        optionLabel="name"
        placeholder="Select a City"
        onChange={(e) => {
            formik.setFieldValue('item', e.value);
        }}
        style={{ width: '15rem' }}
    />
             

    • New York
    • Rome
    • London
    • Istanbul
    • Paris
     
    
    <Toast ref={toast} />
    <Controller
        name="value"
        control={control}
        rules={{ required: 'Value is required.' }}
        render={({ field }) => <ListBox value={field.value} optionLabel="name" placeholder="Select a City" name="value" options={cities} control={control} onChange={(e) => field.onChange(e.value)} style={{ width: '15rem' }} />}
    />
             

    Following is the list of structural style classes, for theming classes visit theming page.

    NameElement
    p-listboxMain container element.
    p-listbox-headerHeader element.
    p-listbox-list-wrapperContainer of list element.
    p-listbox-listList element.
    p-listbox-itemAn item in the list element.
    Accessibility guide documents the specification of this component based on WCAG guidelines, the implementation is in progress.

    Screen Reader

    Value to describe the component can be provided aria-labelledby or aria-label props. The list element has a listbox role with the aria-multiselectable attribute that sets to true when multiple selection is enabled. Each list item has an option role with aria-selected and aria-disabled as their attributes.

    If filtering is enabled, filterInputProps can be defined to give aria-* props to the input element. Alternatively filterPlaceholder is usually utilized by the screen readers as well.

    
    <span id="lb">Options</span>
    <ListBox aria-labelledby="lb" />
    
    <ListBox aria-label="City" />
     

    Keyboard Support

    KeyFunction
    tabMoves focus to the first selected option, if there is none then first option receives the focus.
    up arrowMoves focus to the previous option.
    down arrowMoves focus to the next option.
    enterToggles the selected state of the focused option.
    spaceToggles the selected state of the focused option.
    homeMoves focus to the first option.
    endMoves focus to the last option.
    shift + down arrowMoves focus to the next option and toggles the selection state.
    shift + up arrowMoves focus to the previous option and toggles the selection state.
    shift + spaceSelects the items between the most recently selected option and the focused option.
    control + shift + homeSelects the focused options and all the options up to the first one.
    control + shift + endSelects the focused options and all the options down to the last one.
    control + aSelects all options.
    Visit the API documentation for detailed information about all the properties, events and methods of the component.