jQuery Typeahead Plugin is a autocomplete search functionality that suggest search results from the characters that were typed in the search bar using JavaScript.It gives a search preview text from Json object via same domain Ajax request or cross domain jsonp and offers data compression inside Local Storage. The plugin is built with a lot of options and callbacks to allows customization.
Table of Contents
Key features:
- Cross browser.
- Tons of customization options and callback functions.
- Cross-domain JSONP supported.
- Loading animations.
- Search string highlighting.
- Custom template.
- Keyboard interactions.
- Result group with dropdown filter support.
- ‘localStorage’ or ‘sessionStorage’ caching support.
- Sortable results.
Install it via package managers:
# NPM
$ npm install jquery-typeahead
# Bower
$ bower install jquery-typeahead
Basic usage:
1. First you need to load the following JavaScript and CSS files :
<link rel="stylesheet" href="jquery.typeahead.css">
<script src="jquery.min.js"></script>
<script src="jquery.typeahead.js"></script>
2. Then create an input field:
<input class="js-typeahead"
name="q"
type="search"
autofocus
autocomplete="off">
3. Finally, call the main function on the input field and specify the data source you want to fetch.
$('.js-typeahead').typeahead({
source: {
// local data
groupName: {
data: [ {...}, {...} ]
}
}
});
// or
$('.js-typeahead').typeahead({
source: {
// remote data
groupName: {
ajax: {
url: "..."
}
}
}
});
4. Config the typeahead/autocomplete plugin with the following options.
// *RECOMMENDED*, jQuery selector to reach Typeahead's input for initialization
input: null,
// Accepts 0 to search on focus, minimum character length to perform a search
minLength: 2,
// False as "Infinity" will not put character length restriction for searching results
maxLength: false,
// Accepts 0 / false as "Infinity" meaning all the results will be displayed
maxItem: 8,
// When true, Typeahead will get a new dataset from the source option on every key press
dynamic: false,
// delay in ms when dynamic option is set to true
delay: 300,
// "asc" or "desc" to sort results
order: null,
// Set to true to match items starting from their first character
offset: false,
// Added support for excessive "space" characters
hint: false,
// Will allow to type accent and give letter equivalent results, also can define a custom replacement object
accent: false,
// Added "any" to highlight any word in the template, by default true will only highlight display keys
highlight: true,
// Improved feature, Boolean,string,object(key, template (string, function))
group: false,
// New feature, order groups "asc", "desc", Array, Function
groupOrder: null,
// Maximum number of result per Group
maxItemPerGroup: null,
// Take group options string and create a dropdown filter
dropdownFilter: false,
// Filter the typeahead results based on dynamic value, Ex: Players based on TeamID
dynamicFilter: null,
// Add a backdrop behind Typeahead results
backdrop: false,
// Display the backdrop option as the Typeahead input is :focused
backdropOnFocus: false,
// Improved option, true OR 'localStorage' OR 'sessionStorage'
cache: false,
// Cache time to live in ms
ttl: 3600000,
// Requires LZString library
compression: false,
// Display search results on input focus
searchOnFocus: false,
// Blur Typeahead when Tab key is pressed, if false Tab will go though search results
blurOnTab: true,
// List the results inside any container string or jQuery object
resultContainer: null,
// Forces the source to be generated on page load even if the input is not focused!
generateOnLoad: null,
// The submit function only gets called if an item is selected
mustSelectItem: false,
// String or Function to format the url for right-click & open in new tab on link results
href: null,
// Allows search in multiple item keys ["display1", "display2"]
display: ["display"],
// Display template of each of the result list
template: null,
// Set the input value template when an item is clicked
templateValue: null,
// Set a custom template for the groups
groupTemplate: null,
// Compile display keys, enables multiple key search from the template string
correlativeTemplate: false,
// Display an empty template if no result
emptyTemplate: false,
// // If text is detected in the input, a cancel button will be available to reset the input (pressing ESC also cancels)
cancelButton: true,
// Display a loading animation when typeahead is doing request / searching for results
loading<a href="http://www.jquerypost.com/category/animation/">Animation</a>: true,
// Set to false or function to bypass Typeahead filtering. WARNING: accent, correlativeTemplate, offset & matcher will not be interpreted
filter: true,
// Add an extra filtering function after the typeahead functions
matcher: null,
// Source of data for Typeahead to filter
source: null,
// CSS selectors
selector: {
container: "typeahead__container",
result: "typeahead__result",
list: "typeahead__list",
group: "typeahead__group",
item: "typeahead__item",
empty: "typeahead__empty",
display: "typeahead__display",
query: "typeahead__query",
filter: "typeahead__filter",
filterButton: "typeahead__filter-button",
dropdown: "typeahead__dropdown",
dropdownItem: "typeahead__dropdown-item",
button: "typeahead__button",
backdrop: "typeahead__backdrop",
hint: "typeahead__hint",
cancelButton: "typeahead__cancel-button"
},
// Display debug information (RECOMMENDED for dev environment)
debug: false
5. Callback functions.
callback: {
// When Typeahead is first initialized (happens only once)
onInit: null,
// When the Typeahead initial preparation is completed
onReady: null,
// Called when the layout is shown
onShowLayout: null,
// Called when the layout is hidden
onHideLayout: null,
// When data is being fetched & analyzed to give search results
onSearch: null,
// When the result container is displayed
onResult: null,
// When the result HTML is build, modify it before it get showed
onLayoutBuiltBefore: null,
// Modify the dom right after the results gets inserted in the result container
onLayoutBuiltAfter: null,
// When a key is pressed to navigate the results, before the navigation happens
onNavigateBefore: null,
// When a key is pressed to navigate the results
onNavigateAfter: null,
// When the mouse enter an item in the result list
onMouseEnter: null,
// When the mouse leaves an item in the result list
onMouseLeave: null,
// Possibility to e.preventDefault() to prevent the Typeahead behaviors
onClickBefore: null,
// Happens after the default clicked behaviors has been executed
onClickAfter: null,
// When the dropdownFilter is changed, trigger this callback
onDropdownFilter: null,
// Gets called when the Ajax request(s) are sent
onSendRequest: null,
// Gets called when the Ajax request(s) are all received
onReceiveRequest: null,
// Perform operation on the source data before it gets in Typeahead data
onPopulateSource: null,
// Perform operation on the source data before it gets in Typeahead cache
onCacheSave: null,
// When Typeahead form is submitted
onSubmit: null,
// Triggered if the typeahead had text inside and is cleared
onCancel: null
}