README.md

selector v4

Makes selects great again

When it comes to selects, many people just don't care and use default one. Sometimes it's fine, but if you need more customization, search and beautiful select, you need to use something else. This is selector. A small yet very powerful select plugin. Built with Vite and modern JS. Only 4.2KB gzipped (CSS and icons included)!

Features

• Fully customizable
• Lifecycle hooks and events
• Blazingly fast search feature thanks to options indexing
• Very small, only 4.2KB minified + gzipped, including CSS theme and icons!
• Easy to install and use with npm or yarn
• Built with Vite
• Fully compatible with version 2 and 3! Check selector v2/v3 for compatible methods

How to install selector?

npm and yarn

npm install selector3 --save-dev
yarn add selector3 --dev

Then just require it in your project and you are good to go!

### Add files manually
If you don't use any package manager or build tools, you can still download `dist/` folder manually and include them
in your HTML. Just remember that the `main.js` file needs `type="module"` attribute to work.

## How to use it?
It's pretty simple. You don't have to be genius to use this library. Anyone can!

### Initialize library
```html
<select name="selector" id="selector" data-label="Hello there!">
    <option value="0" selected>Option 1</option>
    <option value="1">Option 2</option>
    <option value="2">Option 3</option>
    <option value="3">Option 4</option>
    <option value="4">Option 5</option>
</select>

and JS:

new Selector({
    element: '#selector'
})

Options, methods and hooks

element option

Defined element where selector initializes. It has to be select HTML element, otherwise it won't initialize. Whether you can define it as string selector or pass the actual element in it.

new Selector({
    element: 'select.my-class'
})

or

const selectElements = document.querySelectorAll('select')
new Selector({
    element: selectElements
})

beforeCreate hook

This hook method is exetuted before selector instance is rendered and ready to use.

new Selector({
    element: 'select.my-class',
    beforeCreate() {
        console.log('Hello world!');
    }
})

created hook

This hook method is exetuted when selector instance is rendered and ready to use.

new Selector({
    element: 'select.my-class',
    created() {
        console.log('Hello world!')
    }
})

opened event

When user clicks on selector element and opens it.

new Selector({
    element: 'select.my-class',
    opened() {
        console.log('Opened!')
    }
})

closed event

When user clicks on selector element and closes it.

new Selector({
    element: 'select.my-class',
    closed() {
        console.log('Closed!')
    }
})

beforeSelect event

Called before value of original select is actually changed. instanceElement is generated selector parent element selectedItem is value of selected option

new Selector({
    element: 'select.my-class',
    beforeSelect(instanceElement, selectedItem) {
        console.log('beforeSelect!')
    }
})

selected event

On option select. instanceElement is generated selector parent element selectedItem is value of selected option

new Selector({
    element: 'select.my-class',
    selected(instanceElement, selectedItem) {
        console.log('Selected!')
    }
})

beforeDestroy hook

Before instance is destroyed with destroy() instance method.

new Selector({
    element: 'select.my-class',
    beforeDestroy() {
        console.log('I am being destroyed!')
    }
})

destroyed hook

After element instance is actually destroyed with destroy() instance method.

new Selector({
    element: 'select.my-class',
    destroyed() {
        console.log('I am destroyed already!')
    }
})

label option

Title of selector displayed when user didn't select any option yet.

new Selector({
    element: 'select.my-class',
    label: 'My selector'
})

type option

Type of selector. At the moment selector has two types: normal and filter. You don't have to provide this option except you want filter inside your selector. Default option is normal. If you want to use filter only in some instances, use data-type attribute with value find or search instead.

new Selector({
    element: 'select.my-class',
    type: 'filter'
})

or using data-type attribute:

<select name="selector" id="selector" data-type="search">
    <option value="0" selected>Option 1</option>
    <option value="1">Option 2</option>
</select>

New in 3.1

disabled option

It is now simple to disable selector instance by setting this option to true. If you don't want to apply disable rule for every element at the beginning, use rather instance methods enable(element) and disable(element). The element parameter is optional if you want to enable/disable all selects. If you only need to affect single select you need to specify which select should be affected. See example below for more.

let instance = new Selector({
    element: 'select.my-class, .my-another-select',
    disabled: true
})

// Query element we want to disable (NOTE that we are querying the original select element)
// Also, don't use .querySelectorAll, it won't work at all!
let disableElement = document.querySelector('select.my-class')

instance.enable()
instance.disable(disableElement)

New in 3.2

identifier option

If you need to use more selector instances on single page, you can use identifier option to distinguish between these instances in DOM. If this option is set, every element in instance has data-identifier attribute with given value.

new Selector({
    element: 'select.my-class',
    identifier: 'firstInstance'
})

cover option

If set to true opened options cover selected item box.

new Selector({
    element: 'select.my-class',
    cover: true
})

relative option

If set to true dropdown is relative positioned.

new Selector({
    element: 'select.my-class',
    relative: true
})