react-dual-listbox

A feature-rich dual listbox for React.

Usage

Installation

Install the library using your favorite dependency manager:

yarn add react-dual-listbox

Using npm:

npm install react-dual-listbox --save

Note – This library makes use of Font Awesome styles and expects them to be loaded in the browser.

Include CSS

The library's styles are available through one of the following files:

• node_modules/react-dual-listbox/lib/react-dual-listbox.css
• node_modules/react-dual-listbox/src/scss/react-dual-listbox.scss

Either include one of these files in your stylesheets or utilize a CSS loader:

import 'react-dual-listbox/lib/react-dual-listbox.css';

Render Component

The DualListBox is a controlled component. You must update the selected property in conjunction with the onChange handler if you want the selected values to change.

Here is a minimal rendering of the component:

import React, { useState } from 'react';
import DualListBox from 'react-dual-listbox';
import 'react-dual-listbox/lib/react-dual-listbox.css';

const options = [
    { value: 'one', label: 'Option One' },
    { value: 'two', label: 'Option Two' },
];

function Widget() {
    const [selected, setSelected] = useState([]);

    return (
        <DualListBox
            options={options}
            selected={selected}
            onChange={(newValue) => setSelected(newValue)}
        />
    );
}

Optgroups

This component also supports traditional <optgroup> elements through the use of the options key:

const options = [
    {
        label: 'Earth',
        options: [
            { value: 'luna', label: 'Moon' },
        ],
    },
    {
        label: 'Mars',
        options: [
            { value: 'phobos', label: 'Phobos' },
            { value: 'deimos', label: 'Deimos' },
        ],
    },
    {
        label: 'Jupiter',
        options: [
            { value: 'io', label: 'Io' },
            { value: 'europa', label: 'Europa' },
            { value: 'ganymede', label: 'Ganymede' },
            { value: 'callisto', label: 'Callisto' },
        ],
    },
];

return <DualListBox options={options} />;

Disabling the Component or Options

Pass in the disabled property to disable the entire component. Alternatively, individual options may be disabled on a per-item basis:

const options = [
    {
        label: 'Mars',
        disabled: true,
        options: [
            { value: 'phobos', label: 'Phobos' },
            { value: 'deimos', label: 'Deimos' },
        ],
    },
    {
        label: 'Jupiter',
        options: [
            { value: 'io', label: 'Io' },
            { value: 'europa', label: 'Europa', disabled: true },
            { value: 'ganymede', label: 'Ganymede' },
            { value: 'callisto', label: 'Callisto' },
        ],
    },
];

return <DualListBox options={options} />;

Filtering

You can enable filtering of available and selected options by merely passing in the canFilter property:

<DualListBox canFilter options={options} />

Optionally, you can also override the default filtering function:

<DualListBox
    canFilter
    filterCallback={(option, filterInput, { getOptionLabel }) => {
        if (filterInput === '') {
            return true;
        }

        return (new RegExp(filterInput, 'i')).test(getOptionLabel(option));
    }}
    options={options}
/>

In addition, you may control the filter text state, rather than leaving it up to the component:

<DualListBox
    canFilter
    filter={{
        available: 'europa',
        selected: '',
    }}
    options={options}
    onFilterChange={(filter) => {
        console.log(filter);
    }}
/>

Action/Button Alignment

By default, the component arranges the action buttons to the center. Another option is to align these actions to be above their respective lists:

<DualListBox alignActions="top" options={options} />

Preserve Select Ordering

By default, react-dual-listbox will order any selected items according to the order of the options property. There may be times in which you wish to preserve the selection order instead. In this case, you can add the preserveSelectOrder property.

Note – Enabling this option hides <optgroup> associations in the selected listbox.

<DualListBox options={options} preserveSelectOrder />

To allow users to re-arrange their selections after moving items to the right, you may also pass in the showOrderButtons property.

Restrict Available Options

Sometimes, it may be desirable to restrict what options are available for selection. For example, you may have a control above the dual listbox that allows a user to search for a planet in the solar system. After selecting a planet, you restrict the available options to the moons of that planet. Use the available property in that case.

// Let's restrict ourselves to the Jovian moons
const available = ['io', 'europa', 'ganymede', 'callisto'];

return <DualListBox options={options} available={available} />;

Changing the Default Icons

By default, react-dual-listbox uses Font Awesome for the various icons that appear in the component. To change the defaults, simply pass in the icons property to override the defaults:

<DualListBox
    ...
    icons={{
        moveToAvailable: <span className="fa fa-chevron-left" />,
        moveAllToAvailable: [
            <span key={0} className="fa fa-chevron-left" />,
            <span key={1} className="fa fa-chevron-left" />,
        ],
        moveToSelected: <span className="fa fa-chevron-right" />,
        moveAllToSelected: [
            <span key={0} className="fa fa-chevron-right" />,
            <span key={1} className="fa fa-chevron-right" />,
        ],
        moveDown: <span className="fa fa-chevron-down" />,
        moveUp: <span className="fa fa-chevron-up" />,
        moveTop: <span className="fa fa-double-angle-up" />,
        moveBottom: <span className="fa fa-double-angle-down" />,
    }}
/>

Alternatively, set the iconsClass property and define the icons in CSS.

Additional onChange Details

At times, it may be useful to know which options the user highlighted before triggering a change or which control group was responsible for the change. In these cases, you can pass additional parameters to the onChange function:

const onChange = (selected, selection, controlKey) => {
    console.log('The user highlighted these options', selection);
    console.log('The following control triggered these changes', controlKey);
};

All Properties

Option Properties