JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 21
  • Score
    100M100P100Q51811F
  • License MIT

A React library providing customizable search dropdown components with single and multi-selection capabilities.

Package Exports

  • dropdowns-js
  • dropdowns-js/style.css

Readme

dropdowns-js

Overview

Searchable dropdown components for React applications.

  • Dropdown - a single selection dropdown whose underlying data is primitive type array.
  • DropdownObj - a single selection dropdown whose underlying data is an array of objects.
  • MultiSelectionDropdown - a multi-selection dropdown whose underlying data is a primitive array.
  • MultiSelectionDropdownObj - a multi-selection dropdown whose underlying data is an array of objects. The components sort the data provided to them.

Installation

npm install dropdowns-js

1. Imports

Inside your component, where you use any of the dropdowns, import as follows: 

// File: MyComponent.jsx
import "dropdowns-js/style.css"; // Must not be left out, so as to enforce dropdown styling.
import {
    Dropdown, // If you use it.
    DropdownObj, // If you use it.
    MultiselectionDropdown, // If you use it.
    MultiselectionDropdownObj,  // If you use it.
} from "dropdowns-js";

export default function MyComponent {
    // ...
}

3. Dropdown Component Attributes

label - the name of the data to be displayed displayed in the dropdown. e.g. Cars, Users.

isDisabled - disables the component when set to true. Default = false.

data - data to display in the dropdown, for the user to select from.

sortDirection - for dropdowns using primitive type array input. Specifies the sort order of the dropdown data. 'asc' or 'desc'. Default is 'asc'.

sortFields - for dropdonws using object type array input. An array. Specifies the field sort orders of the dropdown data. e.g. ['score desc', 'numGames asc']. If a field is to be sorted ascending order, you can ommit asc. .e.g. ['fullName', 'score desc'].

displayName - for dropdowns using object type array input. The field (name) by which the dropdown items will be displayed.

valueName - for dropdowns using object type array input. The name of the field that will be used as the underlying unique value of each dropdown item. e.g. 'code', 'id'.

selectedData - for multi-selection dropdowns. An array of pre-set selection of options. This is an array of multi-selection dropdowns. Optional.

selected - for single selection dropdowns. A pre-set selected option.

onItemSelected - for single selection dropdowns. A function to call when the user has made a selection.

onItemsSelected - for multi-selection dropdowns. A function to call when the user has made a selection. Or removed items from their selection.

dropdownStyle - CSS styling for the dropdown. Fields: {color, backgroundColor, borderColor (optional)}.

buttonStyle - for multi-selecton dropdowns. CSS styling for the DONE button (pressed after completing a selection). Fields: {color, backgroundColor}.

4. Dropdown usage example

This dropdown is to be used when the underlying data is a primitive type array. 

import { Dropdown } from 'dropdowns-js';
import 'dropdowns-js/style.css'; // styles must be imported, otherwise the dropdowns do not display properly.
import { useState } from 'react';

export default function MyComponent() {
    const [output, setOutput] = useState('');
    const fruits = [ "BANANA" "ORANGE", "NAARJIE", "PEACH", "APPLE" ];

    /**Respond when the user has chosen a fruit */
    function fruitSelected(selFruit) {
        setOutput(selFruit);
    }

    return (
        <div className='' style={{padding: '5px', backgroundColor: 'green'}}>
            <h1>Dropdown Example</h1>
            <p>Select a fruit</p>
            <div style={{padding: '2px', display: 'flex'}}> 
                <label htmlFor='fruits' style={{width: '70px'}}>Fruit</label>

                <Dropdown
                    label={'Fruits'}
                    data={fruits} sortDirection='asc'
                    onItemSelected={fruitSelected}
                    selected={"BANANA"}
                    dropdownStyle={{color: '#000', backgroundColor: '#66ff66'}}
                />

            </div>
            <p>{output}</p>

        </div>
    );
}

5. DropdownObj usage example

import { DropdownObj } from 'dropdowns-js';
import 'dropdowns-js/style.css'; // Not to be left out.

import { useState } from 'react';

export default function MyComponent2() {
    const [output, setOutput] = useState('');
    const drivingCodes = [
        { code: 'A1', description: 'Light Motorcycles' },
        { code: 'A', description: 'Heavy Motorcycles' },
        { code: 'B', description: 'Light Vehicles' },
        { code: 'EB', description: 'Light Articulated' },
        { code: 'C1', description: 'Heavy Vehicles' },
        { code: 'C', description: 'Extra Heavy Vehicles' },
        { code: 'EC1', description: 'Heavy Articulated' },
        { code: 'EC', description: 'Extra Heavy Articulated' }
    ];

    /**Respond when the user has chosen a driving code */
    function drivingCodeSelected(selDrivingCode) {
        setOutput(`${selDrivingCode.code} => ${selDrivingCode.description}`);
    }

    return (
        <div className='w3-container' style={{padding: '5px', backgroundColor: 'green'}}>
            <h1>DropdownObj Example</h1>
            <p>Select driving licence code</p>
            <div style={{padding: '2px', display: 'flex'}}> 
                <label htmlFor='driving-codes' style={{width: '70px'}}>Driving Codes</label>

                <DropdownObj
                    label='Driving Codes' data={drivingCodes}
                    displayName="description"
                    valueName="code"
                    sortFields={ ['description'] }
                    onItemSelected={drivingCodeSelected}
                    selected={drivingCodes[0]}
                    dropdownStyle={{color: '#000', backgroundColor: '#66ff66'}} />
            </div>

            <p>{output}</p>
        </div>
    );
}

6. MultiselectionDropdown usage example

import { MultiSelectionDropdown } from 'dropdowns-js';
import 'dropdowns-js/style.css';

import { useState } from 'react';

export default function MyComponent3() {
    const [output, setOutput] = useState('');
    const sport = [
        "Motor Racing", "Cycling", "Wrestling", "Kung Fu", "Boxing", "Basket Ball",
        "Rugby", "Cricket", "Running", "Soccer", "Netball", "Hockey"
    ];

    /**Respond when the user has chosen an interest */
    function sportsSelected(selSports) {
        // Obtain the selected items.
        const selectedSport = selSports("SPORT").join(", );
        setOutput(selectedSport);        
    }

    return (
        <div className='container' style={{padding: '5px', backgroundColor: 'green'}}>
            <h1>MultiSelectionDropdown Example</h1>
            <p>Select an interest, and then your topic</p>
            <div style={{padding: '2px', display: 'flex'}}> 
                <label htmlFor='sport' style={{width: '70px'}}>Sport</label>

                <MultiSelectionDropdown
                    label='Sport'
                    data={sport}
                    onItemsSelected={sportsSelected}
                    dropdownStyle={{color: '#000', backgroundColor: '#66ff66'}}
                    buttonStyle={{color: '#fff', backgroundColor: '#008000'}} />
            </div>

            <>{output}</>
        </div>
    );
}

7. MultiSelectionDropdownObj usage example

import 'dropdowns-js/style.css';
import { MultiSelectionDropdownObj } from 'dropdowns-js';

import { useState } from 'react';


export default function MyComponent4() {
    const [output, setOutput] = useState('');
    const drivingCodes = [
        { code: 'A1', description: 'Light Motorcycles' },
        { code: 'A', description: 'Heavy Motorcycles' },
        { code: 'B', description: 'Light Vehicles' },
        { code: 'EB', description: 'Light Articulated' },
        { code: 'C1', description: 'Heavy Vehicles' },
        { code: 'C', description: 'Extra Heavy Vehicles' },
        { code: 'EC1', description: 'Heavy Articulated' },
        { code: 'EC', description: 'Extra Heavy Articulated' }
    ];

    /**Respond when the user has chosen an interest */
    function drivCodesSelected(selDrivCode) {
        // Create a string array of driving codes.
        const strSelectedCodes = selDrivCodes.map((drivCode)=> drivCode.code)
                                    .map(drivCode => drivCode.code)
                                    .join(", ");
        setOutput(strSelectedCodes);
    }

    return (
        <div className='container' style={{padding: '5px', backgroundColor: 'green'}}>
            <h1>MultiSelectionDropdownObj Example</h1>
            <p>Select an interest, and then your topic</p>
            <div style={{padding: '2px', display: 'flex'}}> 
                <label htmlFor={'driving-licence-codes'} style={{width: '100px'}}>Lic. Codes</label>
                <MultiSelectionDropdownObj
                    label='Driving Licence Codes'
                    data={drivingCodes}
                    sortFields={ ['description'] }
                    valueName='code'
                    displayName='description'
                    onItemsSelected={drivCodeSelected}
                    isDisabled={false}
                    dropdownStyle={{color: '#000', backgroundColor: '#66ff66'}}
                    buttonStyle={{color: '#fff', backgroundColor: '#008000'}} />
            </div>

            {(output.length > 0) &&  
              <div style={{ marginTop: '10px', padding: '5px' }}>
                  {output}
              </div>
            }

        </div>
    );
}

8. Multiple dropdown usage example

export default function MyComponent5() {
    const [output, setOutput] = useState();
     /* A dropdown whose collection data gets updated, must be given a key attribute, so as to update 
        it (key) to cause re-render upon the update of collection data. */
    const [dropdownKey2, setDropdownKey2] = useState(0);
    const keyStep = .000001;

    const { 
        addCollection,
        collectionExists,
        updateCollection,
        getSelected
    } = useCollectionsContext();

    const drivers = [
        { fullName: "Thabo Mokoena", licenceCode: "B", id: "771217" },
        { fullName: "Naledi Khumalo", licenceCode: "EB", id: "850412" },
        { fullName: "Sipho Dlamini", licenceCode: "C1", id: "861802" },
        { fullName: "Ayesha Patel", licenceCode: "B", id: "500101" },
        { fullName: "Johan van der Merwe", licenceCode: "EC", id: "620401" },
        { fullName: "Lerato Molefe", licenceCode: "A", id: "901012" },
        { fullName: "Sibusiso Nkosi", licenceCode: "EC1", id: "910512" },
        { fullName: "Michelle Adams", licenceCode: "B", id: "901012" },
        { fullName: "Kagiso Tshepe", licenceCode: "C", id: "920115" },
        { fullName: "Pieter Botha", licenceCode: "A1", id: "960401" },
        { fullName: "Nomvula Zungu", licenceCode: "B", id: "0792346789" },
        { fullName: "Riaan Pretorius", licenceCode: "EB", id: "0824567812" },
        { fullName: "Mandla Sithole", licenceCode: "C1", id: "0735678910" },
        { fullName: "Fatima Khan", licenceCode: "B", id: "0846789123" },
        { fullName: "Tshepo Madiba", licenceCode: "EC1", id: "0817890234" },
        { fullName: "Andre Nel", licenceCode: "A", id: "0728901345" },
        { fullName: "Zanele Mthembu", licenceCode: "B", id: "0769012456" },
        { fullName: "Imran Desai", licenceCode: "C", id: "0740123567" },
        { fullName: "Charlene Jacobs", licenceCode: "EB", id: "0831234678" },
        { fullName: "Vusi Hlongwane", licenceCode: "EC", id: "0712345789" }
    ];

    useEffect(()=> {
        if (!collectionExists("DRIVING_CODES")) {
            const drivingCodes = [
                "A", "A1", "EC", "EC1", "C", "C1", "B", "EB"
            ];
            // Create DRIVING_CODES collection sorted in ascending order.
            addCollection("DRIVING_CODES", // collection name
                          drivingCodes, // collection data
                          1, // maximum number of selections
                          true, // primitive type data
                          'asc'); // asc - sort order 
        }
        if (!collectionExists("DRIVERS")) {
            // Create a drivers collection sorted in ascending order. Initially empty pending the selection of a driving code.

            addCollection("DRIVERS",
                            [], // empty
                            5, // allow max 5 selections
                            false, // object type data.
                            'fullName asc'); 
        }
    }, []);

    /**Respond when the user has chosen a driving licence code */
    function drivingCodeSelected() {
        // Obtain the selected driving codes.
        const selectedDrivingCodes = getSelected("DRIVING_CODES");

        // Create a string array of driving codes.
        const strSelectedCodes = selectedDrivingCodes; // Expecting a size 1 array
        const selectedCode = strSelectedCodes[0];

        /*=========Update collection according to selected driving licence code=====*/
        const updateData = drivers.filter(driver=> {
            return selectedCode === driver.licenceCode;
        });
        updateCollection("DRIVERS", updateData);
        /*============================================================================*/

        // Force the re-render the drivers MultiselectionDropdownObj, since its data has been updated.
        setDropdownKey2(dropdownKey2 + keyStep);
    }

    function driversSelected() {
        const selectedDrivers = [...getSelected(collectionNames.DRIVERS)].map(driver => driver.fullName); // Array
        setOutput(selectedDrivers.join(', ')); // List of selected drivers' names.
    }

    return (
        <div className='container' style={{padding: '5px', backgroundColor: 'green'}}>
            <h1>MultiSelectionDropdownObj Example</h1>
            <p>Select an interest, and then your topic</p>
            <div style={{padding: '2px', display: 'flex'}}> 
                <label style={{width: '100px'}}>Lic. Codes</label>
                <MultiSelectionDropdownObj label='Driving Licence Codes'
                    collectionName={collectionNames.DRIVING_CODES}
                    valueName='code'
                    displayName='description'
                    onItemsSelected={drivingCodeSelected}
                    isDisabled={false}
                    dropdownStyle={{color: '#000', backgroundColor: '#66ff66'}}
                    buttonStyle={{color: '#fff', backgroundColor: '#008000'}} />
            </div>

            <div style={{padding: '2px', display: 'flex'}}> 
                <label style={{width: '100px'}}>Drivers</label>
                <MultiSelectionDropdownObj
                    key={dropdownKey2}
                    collectionName={collectionNames.DRIVERS}
                    label='Drivers'
                    valueName='id'
                    displayName='fullName'
                    onItemsSelected={driversSelected}
                    dropdownStyle={{color: '#000', backgroundColor: '#66ff66'}}                     
                    buttonStyle={{color: '#fff', backgroundColor: '#008000'}} />               
            </div>

            {output &&  
              <div style={{ marginTop: '10px', padding: '5px' }}>
                  {output}
              </div>
            }

        </div>
    );
}

License

MIT