Custom-select.js NPM

custom-select

Installation

With NPM:

npm install custom-select.js

From a CDN:

Note: There is sometimes a delay before the latest version of the package is available on the CDN.

<script src="https://cdn.jsdelivr.net/npm/custom-select.js@latest/customselect.all.min.js"></script>

Or, if you want to load the CSS separately:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/custom-select.js@latest/customselect.min.css" />

<script src="https://cdn.jsdelivr.net/npm/custom-select.js@latest/customselect.min.js"></script>

Simple Usage

<select id="customSelect_single">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <optgroup label="Group 1">
        <option value="3">Option 3</option>
        <option value="4">Option 4</option>
        <option value="5">Option 5</option>
    </optgroup>
</select>

import CustomSelect from 'custom-select.js'

new CustomSelect("#customSelect_single");

Configs

/********** HTML **********/
<select id="customSelect" multiple>
    <option value="" data-placeholder="true" selected disabled hidden>Please select</option>
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
    <optgroup label="Group 1" data-expanded="off">  // data-expanded="true" (default) || "false" || "off"
        <option value="3">Option 3</option>
        <option value="4">Option 4</option>
        <option value="5">Option 5</option>
    </optgroup>
</select>

/*********** js ***********/
const customSelect = new CustomSelect("#customSelect", {
    options: [                          // if options is empty, it will get options from HTML select element
        <!-- option config -->
        {
            label: "Option 1",          // Required
            value: "Option 1",          // Optional - if value is empty, it will be same as label
            id: "1",                    // Optional - if id is empty, it will be generated automatically
            placeholder: false,         // Optional - if placeholder is true, it will be light gray color as placeholder when it is selected & the value will be empty
            selected: false,            // Optional
            disabled: false,            // Optional
            hidden: false,              // Optional
            class: "",                  // Optional
            style: "",                  // Optional
        },
        <!-- optgroup config -->
        { 
            label: "Group 1",           // Required - if options is set, it will be a group label
            options: [                  // Optional - support multiple level
                { label: "Option 2", value: "Option 2" },
                { label: "Option 3", value: "Option 3" },
            ],
            groupExpanded: "off",       // Optional - true (default) || false || "off"
        },
    ],
    settings: {                        
        allowDeselectAll: false,
        alwaysOpen: false,
        closeOnSelect: true,
        openDirection: "auto",               // "auto" (default) || "up" || "down"
        openPosition: "absolute",            // "absolute" (default) || "relative"
        openLocation: "body",                // HTML element || css selector
        searchEnable: true,
        searchPlaceholder: "Search",
        searchNoResult: "No result",
        searchMark: true,
        selectedOptionHidden: false,
        checkboxMode: false,
        sortMode: false,
        maxValuesShown: 20,
        maxValuesLabel: "{count} selected",  // {count} will be replaced with the number of selected values
        allowHTML: false,
        classNames: {                        // e.g. { select: "class1 class2 class3" }
            select: "cs-select",
            label: "cs-label",
            dropdown: "cs-dropdown",
            listing: "cs-listing",
            option: "cs-option",
            optionGroup: "cs-optionGroup",
            optionGroupLabel: "cs-optionGroup-label",
            optionGroupExpandInput: "cs-optionGroup-expandInput",
            optionGroupListing: "cs-optionGroup-listing",
            arrow: "cs-arrow",
            deselectAll: "cs-deselectAll",
            checkbox: "cs-checkbox",
            relative: "cs-relative",
            openUp: "cs-open-up",
            openDown: "cs-open-down",
            selected: "cs-selected",
            highlighted: "cs-highlighted",
            disabled: "cs-disabled",
            hidden: "cs-hidden",
            selectedHidden: "cs-selectedHidden",
            placeholder: "cs-placeholder",
            searchWrapper: "cs-searchWrapper",
            search: "cs-search",
            searchNoResult: "cs-searchNoResult",
            searchMark: "cs-searchMark",
            selectedItem: "cs-selectedItem",
            selectedItemLabel: "cs-selectedItem-label",
            selectedItemRemove: "cs-selectedItem-remove",
            dndHandle: "cs-dndHandle",
        },
    },
    events: {
        beforeOpen: () => {
            console.log('beforeOpen');
        },
        afterOpen: () => {
            console.log('afterOpen');
        },
        beforeClose: () => {
            console.log('beforeClose');
        },
        afterClose: () => {
            console.log('afterClose');
        },
        beforeChange: (newVal, oldVal) => {
            console.log("[newVal]", newVal);
            console.log("[oldVal]", oldVal);
            // return false will stop the change from happening
        },
        afterChange: (newVal) => {
            console.log("[newVal]", newVal);
        },
        afterSort: (newOptions) => {
            console.log("[newOptions]", newOptions);
        },
    }
});

customSelect.getSelectedValue();              // return string || array (if multiple select)
customSelect.setSelectedValue("value");       // if multiple select, value can be array
customSelect.getSelectedObj();
customSelect.getOptionElBy("key", "value");
customSelect.getOptionObjBy("key", "value");
customSelect.getOptions();
customSelect.setOptions([]);
customSelect.enable();
customSelect.disable();                       // it will revert to the original select element
customSelect.destroy();
customSelect.getSortedOptions();

Configuration Options

allowDeselectAll

Type: Boolean Default: false

Usage: Whether the deselect all button should be shown.

alwaysOpen

Type: Boolean Default: false

Usage: Whether the dropdown should always be open.

closeOnSelect

Type: Boolean Default: true

Usage: Whether the dropdown should be closed after an option is selected.

openDirection

Type: String Default: "auto" Options: "auto", "up", "down"

Usage: The direction of the dropdown when it is opened.

openPosition

Type: String Default: "absolute" Options: "absolute", "relative"

Usage: The position of the dropdown when it is opened.

openLocation

Type: HTMLElement or String Default: "body"

Usage: The location of the dropdown when it is opened.

searchEnable

Type: Boolean Default: true

Usage: Whether the search input should be shown.

searchPlaceholder

Type: String Default: "Search"

Usage: The placeholder of the search input.

searchNoResult

Type: String Default: "No result"

Usage: The text to show when there is no result.

searchMark

Type: Boolean Default: true

Usage: Whether the search result should be highlighted.

selectedOptionHidden

Type: Boolean Default: false

Usage: Whether the selected option should be hidden in the dropdown.

checkboxMode

Type: Boolean Default: false

Usage: If true, the options will apply checkbox style.

sortMode

Type: Boolean Default: false

Usage: If true, the options will be in sort mode. Note: Required to npm install sortablejs

maxValuesShown

Type: Number Default: 20

Usage: The maximum number of values to show in the selected box.

maxValuesLabel

Type: String Default: "{count} selected"

Usage: The label to show when the number of selected values is more than maxValuesShown. {count} will be replaced with the number of selected values.

allowHTML

Type: Boolean Default: false

Usage: Whether HTML should be rendered in all elements. If false, all elements will be treated as plain text. If true, this can be used to perform XSS scripting attacks if you load options from a remote source.

classNames

Type: Object Default:

classNames: {
    select: "cs-select",
    label: "cs-label",
    dropdown: "cs-dropdown",
    listing: "cs-listing",
    option: "cs-option",
    optionGroup: "cs-optionGroup",
    optionGroupLabel: "cs-optionGroup-label",
    optionGroupExpandInput: "cs-optionGroup-expandInput",
    optionGroupListing: "cs-optionGroup-listing",
    arrow: "cs-arrow",
    deselectAll: "cs-deselectAll",
    checkbox: "cs-checkbox",
    relative: "cs-relative",
    openUp: "cs-open-up",
    openDown: "cs-open-down",
    selected: "cs-selected",
    highlighted: "cs-highlighted",
    disabled: "cs-disabled",
    hidden: "cs-hidden",
    selectedHidden: "cs-selectedHidden",
    placeholder: "cs-placeholder",
    searchWrapper: "cs-searchWrapper",
    search: "cs-search",
    searchNoResult: "cs-searchNoResult",
    searchMark: "cs-searchMark",
    selectedItem: "cs-selectedItem",
    selectedItemLabel: "cs-selectedItem-label",
    selectedItemRemove: "cs-selectedItem-remove",
    dndHandle: "cs-dndHandle",
}

Usage: The class names of the elements. E.g. { select: "class1 class2 class3" }