Pw-suggestions NPM

PW Suggestions

Javascript library to autocomplete/suggest values in inputs. It has the following features:

Follows the progressive enhancement strategy: if javascript fails, the web page keeps working
Can get the values from <datalist> or ajax.
Support for <optgroups>.
Build with ES6.
No default CSS styles provided (yes, it's a feature).

Install

Requirements:

NPM or Yarn to install the package and the dependencies
Webpack (or any other javascript loader)

npm install pw-suggestions

Usage

HTML

Let's start with the following html code:

<form>
    <label>
        <input type="text" name="name" list="names" id="name-input">
    </label>
    <datalist id="names">
        <option value="ivan">Ivan</option>
        <option value="pablo">Pablo</option>
        <option value="maria">María</option>
        <option value="alejandro">Alejandro</option>
    </datalist>
</form>

JS

Use javascript for a complete experience:

import {Suggestions, DatalistSource} from 'pw-suggestions';

//Get the input
const input = document.getElementById('name-input');

//Generate the available results from the related <datalist>
const source = new DatalistSource(input);

//Generate the suggestions joining the input and the source values
const suggestions = new Suggestions(input, source);

API

constructor

Create a new instance of Suggestions. The arguments are:

input The input element
source An instance of one of the available sources (see below)

on

select When the user select an option

suggestions.on('select', option => {
    console.log('You has selected the option ', option.label);
});

off

Unregister one or all callbacks of an event

//unregister one callback
suggestions.on('select', callback1);

//unregister all callbacks
suggestions.on('select');

destroy

Unbind all event listener and restore the inputs to the previous state.

The available sources

As you can see, the constructor of the class Suggestions needs two arguments: the input and the source used to search and display the suggestions. There are different sources for different needs:

DatalistSource: Get the source from the <datalist> element associated to the input.
AjaxSource: Get the source from an ajax request returning a json with the data.

Example with ajax:

import {Suggestions, AjaxSource} from 'pw-suggestions';

const suggestions = new Suggestions(
    document.getElementById('my-input'),
    new AjaxSource('/api/suggestions')
);

All sources have the following options:

Name	Type	Description
parent	`Node`	The parent node in which the suggestions are inserted in the DOM. By default is `document.body` unless `DatalistSource` that uses the parent element of the `<datalist>` element.
suggestions.render	`function`	A function to customize the html of each suggestion.
suggestions.label	`string`	The object key used to generate the label of the suggestion. By default is `label`.
suggestions.value	`string`	The object key used to generate the value of the suggestion. By default is `value`.
group.label	`string`	The object key used to generate the label of the group of suggestion. By default is `label`.

Example:

import {Suggestions, AjaxSource} from 'pw-suggestions';

const suggestions = new Suggestions(
    document.getElementById('my-input'),
    new AjaxSource('/api/suggestions', {
        parent: document.getElementById('suggestions-wrapper'),
        suggestions: {
            label: 'title',
            value: 'id',
            render: function (option) {
                return `<strong>${option.label}</strong>`;
            }
        }
    })
);