lara-light-indigo

ListBox

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

Single
  • New York
  • Rome
  • London
  • Istanbul
  • Paris
Grouped
  • Germany
  • Berlin
  • Frankfurt
  • Hamburg
  • Munich
  • USA
  • Chicago
  • Los Angeles
  • New York
  • San Francisco
  • Japan
  • Kyoto
  • Osaka
  • Tokyo
  • Yokohama
Advanced with Templating, Filtering and Multiple Selection
  • Australia
    Australia
  • Brazil
    Brazil
  • China
    China
  • Egypt
    Egypt
  • France
    France
  • Germany
    Germany
  • India
    India
  • Japan
    Japan
  • Spain
    Spain
  • United States
    United States
Virtual Scroll (100000 Items)
    Import via Module
    
    import { ListBox } from 'primereact/listbox';
     
    Import via CDN
    
    <script src="https://unpkg.com/primereact/core/core.min.js"></script>
    <script src="https://unpkg.com/primereact/listbox/listbox.min.js"></script>
     
    Getting Started

    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.

    Options as SelectItems

    
    const citySelectItems = [
        {label: 'New York', value: 'NY'},
        {label: 'Rome', value: 'RM'},
        {label: 'London', value: 'LDN'},
        {label: 'Istanbul', value: 'IST'},
        {label: 'Paris', value: 'PRS'}
    ];
     
    
    <ListBox value={city} options={citySelectItems} onChange={(e) => setCity(e.value)} />
     

    Options as any type

    
    const cities = [
        {name: 'New York', code: 'NY'},
        {name: 'Rome', code: 'RM'},
        {name: 'London', code: 'LDN'},
        {name: 'Istanbul', code: 'IST'},
        {name: 'Paris', code: 'PRS'}
    ];
     
    
    <ListBox optionLabel="name" value={city} options={cities} onChange={(e) => setCity(e.value)} />
    <ListBox optionLabel="name" optionValue="code" value={city} options={cities} onChange={(e) => setCity(e.value)} />
     

    When optionValue is not defined, value of an option refers to the option object itself.

    Selection

    Listbox allows selection of either single or multiple items. In single case, model should be a single object reference whereas in multiple case should be an array. Multiple items can either be selected using metaKey or toggled individually depending on the value of metaKeySelection property value which is true by default. On touch enabled devices metaKeySelection is turned off automatically.

    
    <ListBox value={cities} options={cities} onChange={(e) => setCity(e.value)} multiple />
     
    Custom Content

    Label of an option is used as the display text of an item by default, for custom content support define an itemTemplate property. Its value can be JSXElement, function or string.

    
    <ListBox value={city} options={cities} onChange={(e) => setCity(e.value)} itemTemplate={itemTemplate} />
     
    
    itemTemplate(option) {
        // custom item content
    }
     
    Filtering

    Options can be filtered using an input field in the overlay by enabling the filter property. By default filtering is done against label of the items and filterBy property is available to choose one or more properties of the options. In addition filterMatchMode can be utilized to define the filtering algorithm, valid options are "contains" (default), "startsWith", "endsWith", "equals" and "notEquals". Also, the filterValue and onFilterValueChange properties can be used to control the filter value.

    
    <ListBox value={city} options={cities} onChange={(e) => setCity(e.value)} filter />
     
    Grouping

    Options groups are specified with the optionGroupLabel and optionGroupChildren properties.

    
    const groupedCities = [
        {
            label: 'Germany', code: 'DE',
            items: [
                { label: 'Berlin', value: 'Berlin' },
                { label: 'Frankfurt', value: 'Frankfurt' },
                { label: 'Hamburg', value: 'Hamburg' },
                { label: 'Munich', value: 'Munich' }
            ]
        },
        {
            label: 'USA', code: 'US',
            items: [
                { label: 'Chicago', value: 'Chicago' },
                { label: 'Los Angeles', value: 'Los Angeles' },
                { label: 'New York', value: 'New York' },
                { label: 'San Francisco', value: 'San Francisco' }
            ]
        },
        {
            label: 'Japan', code: 'JP',
            items: [
                { label: 'Kyoto', value: 'Kyoto' },
                { label: 'Osaka', value: 'Osaka' },
                { label: 'Tokyo', value: 'Tokyo' },
                { label: 'Yokohama', value: 'Yokohama' }
            ]
        }
    ];
     
    
    <ListBox value={selectedGroupedCity} options={groupedCities} onChange={(e) => setSelectedGroupedCity(e.value)} optionLabel="label" optionGroupLabel="label" optionGroupChildren="items" />
     
    SelectItem API
    NameTypeDefaultDescription
    labelstringnullLabel of the option.
    valuestringnullValue of the option.
    classNamestringnullClassName of the option.
    titlestringnullTooltip text of the option. (Not supported)
    disabledbooleanfalseWhether the option is disabled or not. (Not supported)
    Properties
    NameTypeDefaultDescription
    idstringnullUnique identifier of the element.
    valueobjectnullSelected value to display.
    optionsarraynullAn array of objects to display as the available options.
    optionLabelstringnullName of the label field of an option when an arbitrary objects instead of SelectItems are used as options.
    optionValuestringnullName of the value field of an option when arbitrary objects are used as options instead of SelectItems.
    optionDisabledfunction | stringnullProperty name or getter function to use as the disabled flag of an option, defaults to false when not defined.
    optionGroupLabelstringnullProperty name or getter function to use as the label of an option group.
    optionGroupChildrenstringnullProperty name or getter function that refers to the children options of option group.
    itemTemplateanynullCustom template for the items.
    optionGroupTemplateanynullTemplate of an option group item.
    stylestringnullInline style of the element.
    listStyleobjectnullInline style of inner list element.
    listClassNamestringnullInline style class of inner list element.
    classNamestringnullStyle class of the element.
    disabledbooleanfalseWhen specified, disables the component.
    dataKeystringfalseA property to uniquely match the value in options for better performance.
    multiplebooleanfalseWhen specified, allows selecting multiple values.
    metaKeySelectionbooleantrueDefines how multiple items can be selected, when true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically.
    filterbooleanfalseWhen specified, displays a filter input at header.
    filterBystringlabelWhen filtering is enabled, filterBy decides which field or fields (comma separated) to search against.
    filterValuestringnullWhen specified, filter displays with this value.
    filterMatchModestringcontainsDefines how the items are filtered, valid values are "contains" (default), "startsWith", "endsWith", "equals" and "notEquals".
    filterPlaceholderstringnullPlaceholder text to show when filter input is empty.
    filterLocalestringundefinedLocale to use in filtering. The default locale is the host environment's current locale.
    tabIndexnumbernullIndex of the element in tabbing order.
    tooltipanynullContent of the tooltip.
    tooltipOptionsobjectnullConfiguration of the tooltip, refer to the tooltip documentation for more information.
    virtualScrollerOptionsobjectnullWhether to use the virtualScroller feature. The properties of VirtualScroller component can be used like an object in it.
    Events
    NameParametersDescription
    onChangeevent.originalEvent: Browser event
    event.value: Single value or an array of values depending on the selection mode
    Callback to invoke when value of listbox changes.
    onFilterValueChangeevent.originalEvent: Browser event
    event.value: the filtered value
    Callback to invoke when filter value changes.
    Styling

    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.
    Dependencies

    None.

    Component Scale

    Input Style

    Ripple Effect

    Free Themes

    Built-in component themes created by the PrimeReact Theme Designer.

    Bootstrap
    Blue
    Purple
    Blue
    Purple
    Material Design
    Indigo
    Deep Purple
    Indigo
    Deep Purple
    Material Design Compact
    Indigo
    Deep Purple
    Indigo
    Deep Purple
    Tailwind
    Tailwind Light
    Fluent UI
    Blue
    PrimeOne Design - 2022 NEW
    Lara Indigo
    Lara Blue
    Lara Purple
    Lara Teal
    Lara Indigo
    Lara Blue
    Lara Purple
    Lara Teal
    PrimeOne Design - 2021
    Saga Blue
    Saga Green
    Saga Orange
    Saga Purple
    Vela Blue
    Vela Green
    Vela Orange
    Vela Purple
    Arya Blue
    Arya Green
    Arya Orange
    Arya Purple
    Premium Themes

    Premium themes are only available exclusively for PrimeReact Theme Designer subscribers and therefore not included in PrimeReact core.

    Soho Light
    Soho Dark
    Viva Light
    Viva Dark
    Mira
    Nano

    Legacy Free Themes

    Nova
    Nova Alt
    Nova Accent
    Luna Blue
    Luna Green
    Luna Amber
    Luna Pink
    Rhea

    Premium Create-React-App Templates

    Beautifully crafted premium create-react-app application templates by the PrimeTek design team.

    Sakai
    Atlantis
    Freya
    Ultima
    Diamond
    Sapphire
    Serenity
    Babylon
    Avalon
    Apollo
    Roma