Easy Select

Demo: https://easy-select.netlify.app

Getting started

CDN

<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/viivue/[email protected]/dist/easy-select.min.css">

<script src="https://cdn.jsdelivr.net/gh/viivue/[email protected]/dist/easy-select.min.js"></script>

NPM Package

Install NPM package

npm i @viivue/easy-select

Import

import "@viivue/easy-select";

Initialize

With HTML

Using these HTML attributes to initialize without JavaScript.

<!-- Init with HTML attribute -->
<select data-easy-select>
    <option value="1">One</option>
    <option value="2">Two - Hai</option>
    <option value="3">Three - 第三的</option>
</select>

With JavaScript

Assume that we have the HTML like below

<select id="my-select">
    <option value="1">One</option>
    <option value="2">Two - Hai</option>
    <option value="3">Three - 第三的</option>
</select>

// jQuery plugin
jQuery('#my-select').easySelect();

// DOM element
EasySelect.init(document.querySelector('#my-select'));

// jQuery element
EasySelect.init(jQuery('#my-select'));

// CSS selector string
EasySelect.init('#my-select');

Options

All options are optional.

| Attribute | Type | Default | Description | |---------------------|---------|--------------------------|--------------------------------------------------------------------------------------------------| | id | string | Auto-generated ID | Set an ID to access this select later with EasySelect.get() | | nativeSelect | boolean | false | Use native select instead of a custom dropdown | | align | string | "left" | Set alignment for dropdown. Could be "top" or "top right". Visit demo page for full options. | | closeOnChange | boolean | true | Close dropdown on value changes. | | search | boolean | false | Show a field to search options inside the dropdown. | | emptySearchText | string | "There are no options" | Text when no search results found | | searchPlaceHolder | string | "Type to search..." | Placeholder for the search input |

EasySelect.init('#my-select', {
    id: 'my-select',
    align: "top right"
});

Set options via HTML

Pass a string to use as ID

<!-- Init with custom ID -->
<select data-easy-select="my-id">
    <option value="1">One</option>
</select>

Pass a valid JSON to use as options

<!-- Init with options -->
<select data-easy-select='{ "id":"my-id", "align":"right" }'>
    <option value="1">One</option>
</select>

⚠️ Options set in HTML must be valid JSON. Keys need to be quoted, for example "align":"right".

Methods

| Usage | Description | |-------------------------------------------------|-----------------------------------------------------------| | instance.toggle() | Toggle open/close | | instance.open() | Open dropdown | | instance.close() | Close dropdown | | instance.disable() | Disable select | | instance.disableOption(optionValue, disabled) | Disable/enable an option | | instance.enable() | Enable select | | instance.refresh() | Refresh select when original select changes with new HTML | | instance.destroy() | Destroy select, return original HTML | | instance.select(value) | Select a value | | instance.add(value, label) | Add new option with value and label | | instance.on(eventName, callback) | Assign events |

// init
EasySelect.init('#my-select', {
    id: 'my-select'
});

// get instance
const instance = EasySelect.get('my-select');

// use method
instance.open();

Events

| Usage | Description | |--------------------------|-----------------------------------------------------------------------------| | beforeInit: data => {} | Before init | | onInit: data => {} | After init | | onRefresh: data => {} | After refresh | | onChange: data => {} | After value changed, the same as select.addEventListener('change',()=>{}) | | onDestroy: data => {} | After destroy | | onDisable: data => {} | After disable | | onEnable: data => {} | After enable | | onOpen: data => {} | After open | | onClose: data => {} | After close | | onToggle: data => {} | After toggle, before open or close | | onAdded: data => {} | After a new item was added successfully |

EasySelect.init('#my-select', {
    id: 'my-select',
    onChange: data => {
        console.log(data);
    }
});

// add event via method on()
const instance = EasySelect.get('my-select');
instance.on('change', () => {
    // do something
});

Deployment

# Run dev server
npm run dev

# Build dev site
npm run build

# Generate production files
npm run prod

License

MIT License

Copyright (c) 2023 ViiVue