Flexible Facebook-like auto-complete widget for jQuery

Introduction

Turn a text input into a Facebook-style multiple-tag input. Features include:

Load data from a JavaScript array, object, json url, or jsonp url
Lots of options
Populates original input with chosen tags but also creates hidden inputs with ids and tag text
Has methods to add a tag programmatically (e.g. user chooses a popular tag)
CSS is easy to extend and customize
CSS uses em units so that you can easily size the widget however you like
You can subscribe to any of 20+ events that allow you to inject custom functionality into nearly every action
You can define your own HTML structure for the widget output
Object-oriented structure makes it easy to extend
Unit tested - Unit tests
Works on IE8+, FF, Chrome, Safari
5kb minimized and gzipped
Compatible with AMD

How to Use

Suggester is compatible with jQuery 1.5+ and has been unit tested with jQuery 1.9. Download the files in Suggester-1.4.0-Download.zip and copy them to your scripts directory. Include them in your document’s after jQuery is included:

<script src="/js/Suggester.min.js"></script>
<link  href="/js/Suggester.min.css" rel="stylesheet" />

Then somewhere in your code, call:

var instance = new $.Suggester(selector, options);
// OR
$(selector).suggester(options);

See the documentation below for a full list of options.

Events

Events can be passed as options to the constructor, or can be added later using jQuery event methods .on(), .off(), .bind() .one(), .unbind() and .trigger()

For example:

// Register events in initial options
$(input).suggester({
	data: myData,
	onBeforeOpen: doStuff
});
// Register events later (OOP style)
var instance = new $.Suggester(selector, {
	data: myData
});
instance.on('BeforeOpen', doStuff);
// Register events later (jQuery style)
$(input).suggester({
	data: myData
}).suggester('on', 'BeforeOpen', doStuff);

How is data passed to event callbacks?

Each event callback receives one argument: event
event is a jQuery event object
event also contains useful information related to the event. See the Events section below for more information.
When an event has a default action that can be prevented, event will have property cancelable set to true and event.isCancelable() will return true
To prevent a default action, call event.preventDefault()
To cancel the firing of other attached callbacks, call event.stopImmediatePropagation()
In some case, altering information on the event object will change the behavior of the default action
The callback will be fired in the scope of the Suggester instance. In other words, using this in the callback will refer to the Suggester instance. See the Instance Properties and Instance Methods sections below for more information.

Instance Methods

Instance methods may be called using an Object Oriented style or with the classic jQuery style:

// Object Oriented Style
var suggester = new $.Suggester(input, options);
suggester.methodName(arg1, arg2, argN);

// jQuery Style
$(input).suggester(options);
$(input).suggester('methodName', arg1, arg2, argN);

// jQuery Style followed by Object Oriented Style
$(input).suggester(options);
var instance = $(input).suggester('getInstance');
instance.methodName(arg1, arg2, argN);

More examples

Use an array of strings for suggestions:

$('.my-text-input').suggester({
    data: ['Monday','Tuesday','Wednesday','Thursday','Friday','Saturday','Sunday'],
    prompt: 'Enter a day of the week'
});

Use ajax to get suggestions:

$('.my-text-input').suggester({
    dataUrl: 'http://example.com/myjson?query=%s',
    prompt: 'Enter a time zone'
});

Use the OOP pattern and use an array of objects for data:

var suggester = new $.Suggester('.my-text-input', {
	data: [{"label":"John Doe","value":"John Doe <John.Doe@example.com>"}/*,...*/],
    onAfterSave: function(event) {
        saveToServer(event.newValue);
    }
});
suggester.on('AfterClose', doStuff);
suggester.focus();

See the source on the live demos for lots more examples.

Changelog

Version 1.4.0, Aug 2014

new event DefaultSuggestions
cite some jsPerf results
change ‘bind’ to ‘on’ in examples and internal usage
change default keyDelay to 200ms
fix docs for static properties and methods

Version 1.3.1, Apr 2014

Fix to hidePlaceholder()
Fix input hidden name

Version 1.3.0, Mar 2014

Fixes to setValue(), clear(), focus(), blur()
Use git watch
Documentation improvements
More unit tests

Version 1.2.2, Jul 2013

Fixes to add()
Documentation improvements
More unit tests

Version 1.2.1, Jul 2013

Added onChange event
Documentation fixes
Tweaks on build process

Version 1.2.0, Jun 2013

Allow pasting delimited values
Speed improvements
Search through this.data to find typed values when applicable

Version 1.1.1, May 2013

Fixed Suggester#getValues()

Version 1.1.0, May 2013

Grunt build process
Suggester.tags is now a collection of $.Suggester.Tag objects

Version 1.0.2, April 2013

CSS classes for sugg-active and sugg-placeholder-on
Fix BeforeAdd event to let value to be altered and AfterAdd event to include record
Documentation fixes

Version 1.0pre, December 2012

initial version

Contributing

After using git to clone the repo, you’ll need nodejs, npm, and grunt-cli installed. See gruntjs.com for more information. Then inside the cloned directory run npm install and then grunt

Make updates only to the files in the ./src directory. Then run grunt to automatically generate documentation and other files. You may also make changes to the demos by editing ./demos/* files or improve the build process by editing ./Gruntfile.js. Then make a pull request.

Reporting Bugs

To report bugs, add an issue to the GitHub issue tracker.

Download Details:

Author: kensnyder

Live Demo: http://sandbox.kendsnyder.com/jQuery-Suggester/demos/

GitHub: https://github.com/kensnyder/jQuery-Suggester

#jquery #javascript