Select-4 NPM | npm.io

select4

Zero dependency (~1 KiB) autocomplete and multiselect control for the web. Inspired by select2 and select3.

select4

Installation

To install, using npm:

npm i select-4

Usage

To turn a select input into select4, use:

import {select4} from 'select-4'
import "select-4/dist/style-bootstrap.css" // with bootstrap 5 styles; Otherwise just use style.css

select4(selectInput, options)

Quick Start

If you have got an HTML select control as:

<select name="select-fruits" id="select-fruits"></select>

...

const mySelect = document.getElementById('select-fruits')

then you can transform it into a select4 using:

import {select4} from 'select-4'
import "select-4/dist/style.css"

select4(mySelect, {
    dataSource: ['Apple', 'Orange', 'Banana', 'Mango', 'Guava', 'Strawberry'],
})

You can see the values from your original select input:

const values = Array.from(mySelect.querySelectorAll("option:checked"), e => e.value);

To listen to changes:

select4(mySelect,{
    dataSource: ...,
    onChange: selections => console.log('Selected:', selections)
})

If you have a remote REST API as a datasource, use:

select4(document.getElementById('search-wikipedia'), {
    dataSource: async (filter) => {
        const res = await fetch('https://en.wikipedia.org/w/api.php?action=opensearch&origin=*&search=' + filter)
        if (res.ok) {
            const result = (await res.json())
            return result[1].map((i, index) => ({title: i, link: result[3][index]}))
        }
        return []
    },
    valueTemplate: (item, _) => `<a href="${item.link}">${item.title}</a>`,
    suggestionItemTemplate: (item, _) => item.title,
})

The above code with the bootstrap styling would result:

An even more elaborate example would be an XKCD comics search. Configure it as:

valueTemplate: (item, _) => `<a href="${item.link}">${item.title}</a>`,
suggestionItemTemplate: (item, _) =>
    `
    <hr>
    <h4 style="margin: 0">
        ${item.title}
        &nbsp;<small style="border: 1px solid black; background: grey; color: white">${item.year}</small>
    </h4>            
    <div>
        <img src="${item.img}" height="48px">
    </div>`

which would result in something like:

You can find examples in src/examples.ts file.

Options

Option	Description	Type
`dataSource`*	Function called to search for values based on search key. You can also supply a simple array, or use the `staticDataSource()` method.	`Array` or `async function (searchKey: string) => []any`
`multiple`	Whether multiple selection is allowed	`boolean`
`maxItems`	Max number of results to show	`number`
`whenEmptyTemplate`	HTML to display when there are no items	`string`
`whenErrorTemplate`	HTML to display when there was an error fetching from the data source	`function (error: any) => string`
`valueAdapter`	A map function called to extract the final value when a search result item is selected. For example, `i => ({key: i.Name, value: i.Id})`	`function (item) => any`
`suggestionsRenderer`	Custom function to be called to render search results. Use this if you want to override the default suggestions panel creation.	`function (list: []any, instance) => void`
`valuesRenderer`	Function called to render values. Use this if you want to override the default values list item creation.	`function (list: []any, instance) => void`
`filterInputElement`	Function to setup the filter input. For example, `input => input.classList.add('form-control')`	`function (input: HTMLInputElement) => void`
`valueElement`	A function to setup each value html element. For example, `(i, elt) => elt.setAttribute('style', 'color: red; border: 1px solid green;')`	`function (value: any, element: HTMLElement) => void`
`suggestionsContainerElement`	A function to setup the suggestions container div.	`function (container: HTMLElement) => void`
`suggestionItemElement`	A function to setup each suggestion html element.	`function (suggestionElt: HTMLElement) => void`
`valueTemplate`	HTML template string for each value item. For example, (i, _) => `<a href="${i.Link}">${i.Title}</a>`	`function (item, instance) => string`
`suggestionItemTemplate`	HTML template string for each suggestion item. For example, `(i, _) => i.Title`	`function (item, instance) => string`
`busyAnimation`	Whether to animate the busy indicator	`boolean`

Events

You can handle the following events by specifying in the config options.

Option	Description	Type
`onError`	Error handler function, called when data source call throws an exception	`function (err: any, instance) => void`
`onChange`	Event triggered when selection changes. For example, `selected_items => console.log('change', selected_items)`	`function (items: Array) => void`

Styling

Default styles are included in style.css file. You can add a css for the following classes:

Css Class	Description
`select4-input`	The search input
`select4-suggestions`	Suggestions container panel
`select4-suggest-item`	Individual suggested item
`select4-values`	Values panel
`select4-value`	Individual value item
`select4-value-btn`	The remove button for each value item
`select4-busy`	The busy indicator
`select4-error`	The error panel
`select4-no-result`	The container shown when there are no results