custom-select

Demo

Installation

With NPM:

``

bash

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.

html





Or, if you want to load the CSS separately:

html





Simple Usage

html

js

import CustomSelect from 'custom-select.js'



new CustomSelect("#customSelect_single");





Configs

js

/ HTML /





/ js /

const customSelect = new CustomSelect("#customSelect", {

    options: [                          // if options is empty, it will get options from HTML select element

        

        {

            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

        },

        

        { 

            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



$3



Type:

Boolean Default: false





Usage: Whether the deselect all button should be shown.



$3



Type:

Boolean Default: false





Usage: Whether the dropdown should always be open.



$3



Type:

Boolean Default: true





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



$3



Type:

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





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



$3



Type:

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





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



$3



Type:

HTMLElement or String Default: "body"





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



$3



Type:

Boolean Default: true





Usage: Whether the search input should be shown.



$3



Type:

String Default: "Search"





Usage: The placeholder of the search input.



$3



Type:

String Default: "No result"





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



$3



Type:

Boolean Default: true





Usage: Whether the search result should be highlighted.



$3



Type:

Boolean Default: false





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



$3



Type:

Boolean Default: false





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



$3



Type:

Boolean Default: false





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

npm install sortablejs





$3



Type:

Number Default: 20





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



$3



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.



$3



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.



$3



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" }`

Events

$3

Usage: Triggered before the dropdown is opened.

$3

Usage: Triggered after the dropdown is opened.

$3

Usage: Triggered before the dropdown is closed.

$3

Usage: Triggered after the dropdown is closed.

$3

Usage: Triggered before the value is changed.

$3

Usage: Triggered after the value is changed.

$3

Usage: Triggered after the options are sorted.

Methods

$3

Usage: Get the selected value(s).

$3

Usage: Set the selected value(s). If multiple select, value can be array.

$3

Usage: Get the selected option object(s).

$3

Usage: Get the option element by the key and value.

$3

Usage: Get the option object by the key and value.

$3

Usage: Get the options.

$3

Usage: Set the options.

$3

Usage: Enable the dropdown.

$3

Usage: Disable the dropdown.

$3

Usage: Destroy the dropdown.

custom-select

Demo

Installation

With NPM:

``

bash

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.

html





Or, if you want to load the CSS separately:

html





Simple Usage

html

js

import CustomSelect from 'custom-select.js'



new CustomSelect("#customSelect_single");





Configs

js

/ HTML /





/ js /

const customSelect = new CustomSelect("#customSelect", {

    options: [                          // if options is empty, it will get options from HTML select element

        

        {

            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

        },

        

        { 

            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



$3



Type:

Boolean Default: false





Usage: Whether the deselect all button should be shown.



$3



Type:

Boolean Default: false





Usage: Whether the dropdown should always be open.



$3



Type:

Boolean Default: true





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



$3



Type:

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





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



$3



Type:

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





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



$3



Type:

HTMLElement or String Default: "body"





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



$3



Type:

Boolean Default: true





Usage: Whether the search input should be shown.



$3



Type:

String Default: "Search"





Usage: The placeholder of the search input.



$3



Type:

String Default: "No result"





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



$3



Type:

Boolean Default: true





Usage: Whether the search result should be highlighted.



$3



Type:

Boolean Default: false





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



$3



Type:

Boolean Default: false





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



$3



Type:

Boolean Default: false





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

npm install sortablejs





$3



Type:

Number Default: 20





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



$3



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.



$3



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.



$3



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" }`

Events

$3

Usage: Triggered before the dropdown is opened.

$3

Usage: Triggered after the dropdown is opened.

$3

Usage: Triggered before the dropdown is closed.

$3

Usage: Triggered after the dropdown is closed.

$3

Usage: Triggered before the value is changed.

$3

Usage: Triggered after the value is changed.

$3

Usage: Triggered after the options are sorted.

Methods

$3

Usage: Get the selected value(s).

$3

Usage: Set the selected value(s). If multiple select, value can be array.

$3

Usage: Get the selected option object(s).

$3

Usage: Get the option element by the key and value.

$3

Usage: Get the option object by the key and value.

$3

Usage: Get the options.

$3

Usage: Set the options.

$3

Usage: Enable the dropdown.

$3

Usage: Disable the dropdown.

$3

Usage: Destroy the dropdown.