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

Register events in the page loader workflow. The available events are:

• 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>`;
            }
        }
    })
);

Demo

To run the demo, just clone this repository enter in the directory and execute:

npm install
npm start

You should see something in http://localhost:8080/