select4

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

• select4
  • Installation
  • Usage
  • Quick Start
  • Options
  • Events
  • Styling
  • Development

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 |

Development

To run samples:

npm run dev

To build everything:

npm run build