typeahead.js

Inspired by twitter.com's autocomplete search functionality, typeahead.js is a fast and fully-featured autocomplete library.

Getting Started

How you acquire typeahead.js is up to you.

Preferred method:

• Install with Bower: $ bower install typeahead.js

Other methods:

• Download zipball of latest release.
• Download latest typeahead.js or typeahead.min.js.

Note: typeahead.js has a dependency on jQuery 1.9+, which must be loaded before typeahead.js.

Examples

For some working examples of typeahead.js, visit our examples page.

Features

• Displays suggestions to end-users as they type
• Shows top suggestion as a hint (i.e. background text)
• Works with hardcoded data as well as remote data
• Rate-limits network requests to lighten the load
• Allows for suggestions to be drawn from multiple datasets
• Supports customized templates for suggestions
• Plays nice with RTL languages and input method editors

Why not use X?

At the time Twitter was looking to implement a typeahead, there wasn't a solution that allowed for prefetching data, searching that data on the client, and then falling back to the server. It's optimized for quickly indexing and searching large datasets on the client. That allows for sites without datacenters on every continent to provide a consistent level of performance for all their users. It plays nicely with Right-To-Left (RTL) languages and Input Method Editors (IMEs). We also needed something instrumented for comprehensive analytics in order to optimize relevance through A/B testing. Although logging and analytics are not currently included, it's something we may add in the future.

Usage

API

jQuery#typeahead(datasets)

Turns any input[type="text"] element into a typeahead. datasets is expected to be a single dataset or an array of datasets.

// single dataset
$('input.typeahead-devs').typeahead({
  name: 'accounts',
  local: ['timtrueman', 'JakeHarding', 'vskarich']
});

// multiple datasets
$('input.twitter-search').typeahead([
  {
    name: 'accounts',
    prefetch: 'https://twitter.com/network.json',
    remote: 'https://twitter.com/accounts?q=%QUERY'
  },
  {
    name: 'trends',
    prefetch: 'https://twitter.com/trends.json'
  }
]);

jQuery#typeahead('destroy')

Destroys previously initialized typeaheads. This entails reverting DOM modifications and removing event handlers.

$('input.typeahead-devs').typeahead({
  name: 'accounts',
  local: ['timtrueman', 'JakeHarding', 'vskarich']
});

$('input.typeahead-devs').typeahead('destroy');

jQuery#typeahead('setQuery', query)

Sets the current query of the typeahead. This is always preferable to using $("input.typeahead").val(query), which will result in unexpected behavior. To clear the query, simply set it to an empty string.

Dataset

A dataset is an object that defines a set of data that hydrates suggestions. Typeaheads can be backed by multiple datasets. Given a query, a typeahead instance will inspect its backing datasets and display relevant suggestions to the end-user.

When defining a dataset, the following options are available:

• name – The string used to identify the dataset. Used by typeahead.js to cache intelligently.

• valueKey – The key used to access the value of the datum in the datum object. Defaults to value.

• limit – The max number of suggestions from the dataset to display for a given query. Defaults to 5.

• template – The template used to render suggestions. Can be a string or a precompiled template (i.e. a function that takes a datum as input and returns html as output). If not provided, suggestions will render as their value contained in a <p> element (i.e. <p>value</p>).

• engine – The template engine used to compile/render template if it is a string. Any engine can be used as long as it adheres to the expected API. Required if template is a string.

• header – The header rendered before suggestions in the dropdown menu. Can be either a DOM element or HTML.

• footer – The footer rendered after suggestions in the dropdown menu. Can be either a DOM element or HTML.

• local – An array of datums.

• prefetch – Can be a URL to a JSON file containing an array of datums or, if more configurability is needed, a prefetch options object.

• remote – Can be a URL to fetch suggestions from when the data provided by local and prefetch is insufficient or, if more configurability is needed, a remote options object.

Datum

The individual units that compose datasets are called datums. The canonical form of a datum is an object with a value property and a tokens property. value is the string that represents the underlying value of the datum and tokens is a collection of single-word strings that aid typeahead.js in matching datums with a given query.

{
  value: '@JakeHarding',
  tokens: ['Jake', 'Harding']
}

For ease of use, datums can also be represented as a string. Strings found in place of datum objects are implicitly converted to a datum object.

When datums are rendered as suggestions, the datum object is the context passed to the template engine. This means if you include any arbitrary properties in datum objects, those properties will be available to the template used to render suggestions.

<img src="{{profileImageUrl}}">
<p><strong>{{name}}</strong>&nbsp;{{value}}</p>

{
  value: '@JakeHarding',
  tokens: ['Jake', 'Harding'],
  name: 'Jake Harding',
  profileImageUrl: 'https://twitter.com/JakeHaridng/profile_img'
}

Prefetch

Prefetched data is fetched and processed on initialization. If the browser supports localStorage, the processed data will be cached there to prevent additional network requests on subsequent page loads.

When configuring prefetch, the following options are available:

• url – A URL to a JSON file containing an array of datums. Required.

• ttl – The time (in milliseconds) the prefetched data should be cached in localStorage. Defaults to 86400000 (1 day).

• filter – A function with the signature filter(parsedResponse) that transforms the response body into an array of datums. Expected to return an array of datums.

Remote

Remote data is only used when the data provided by local and prefetch is insufficient. In order to prevent an obscene number of requests being made to remote endpoint, typeahead.js rate-limits remote requests.

When configuring remote, the following options are available:

• url – A URL to make requests to when the data provided by local and prefetch is insufficient. Required.

• dataType – The type of data you're expecting from the server. See the jQuery.ajax docs for more info. Defaults to json.

• cache – Determines whether or not the browser will cache responses. See the jQuery.ajax docs for more info.

• timeout – Sets a timeout for requests. See the jQuery.ajax docs for more info.

• wildcard – The pattern in url that will be replaced with the user's query when a request is made. Defaults to %QUERY.

• replace – A function with the signature replace(url, uriEncodedQuery) that can be used to override the request URL. Expected to return a valid URL. If set, no wildcard substitution will be performed on url.

• rateLimitFn – The function used for rate-limiting network requests. Can be either debounce or throttle. Defaults to debounce.

• rateLimitWait – The time interval in milliseconds that will be used by rateLimitFn. Defaults to 300.

• maxParallelRequests – The max number of parallel requests typeahead.js can have pending. Defaults to 6.

• beforeSend – A pre-request callback with the signature beforeSend(jqXhr, settings). Can be used to set custom headers. See the jQuery.ajax docs for more info.

• filter – A function with the signature filter(parsedResponse) that transforms the response body into an array of datums. Expected to return an array of datums.

Custom Events

typeahead.js triggers the following custom events:

• typeahead:initialized – Triggered after initialization. If data needs to be prefetched, this event will not be triggered until after the prefetched data is processed.

• typeahead:opened – Triggered when the dropdown menu of a typeahead is opened.

• typeahead:closed – Triggered when the dropdown menu of a typeahead is closed.

• typeahead:selected – Triggered when a suggestion from the dropdown menu is explicitly selected. The datum for the selected suggestion is passed to the event handler as an argument in addition to the name of the dataset it originated from.

• typeahead:autocompleted – Triggered when the query is autocompleted. The datum used for autocompletion is passed to the event handler as an argument in addition to the name of the dataset it originated from.

All custom events are triggered on the element initialized as a typeahead.

$('input.typeahead-devs').typeahead({
    name: 'accounts',
    local: [{
        value: '@JakeHarding',
        tokens: ['Jake', 'Harding'],
        name: 'Jake Harding',
        profileImageUrl: 'https://twitter.com/JakeHaridng/profile_img'
    }]
});

$('input.typeahead-devs').on('typeahead:selected', function (object, datum) {
    // Example: {type: "typeahead:selected", timeStamp: 1377890016108, jQuery203017338529066182673: true, isTrigger: 3, namespace: ""...}
    console.log(object);

    // Datum containg value, tokens, and custom properties
    // Example: {value: "@JakeHarding", tokens: ['Jake', 'Harding'], name: "Jake Harding", profileImageUrl: "https://twitter.com/JakeHaridng/profile_img"}
    console.log(datum);
});

Template Engine Compatibility

Any template engine will work with typeahead.js as long as it adheres to the following API:

// engine has a compile function that returns a compiled template
var compiledTemplate = ENGINE.compile(template);

// compiled template has a render function that returns the rendered template
// render function expects the context to be first argument passed to it
var html = compiledTemplate.render(context);

Check out Hogan.js if you're looking for a compatible mustache templating engine.

Look and Feel

The styles applied by typeahead.js are for positioning the hint and the dropdown menu, no other styles should be affected. In most cases the styles applied by typeahead.js will work like a charm, but there are edge cases where some custom styles will be necessary. If you're having CSS issues, create an issue or tweet @typeahead for support.

By default, the dropdown menu created by typeahead.js is going to look ugly and you'll want to style it to ensure it fits into the theme of your web page. Below is a Mustache template describing the DOM structure of a typeahead.js dropdown menu. Note that the {{{html}}} tag is the HTML generated by the custom template you provide when defining datasets.

<span class="tt-dropdown-menu">
  {{#dataset}}
    <div class="tt-dataset-{{name}}">
      {{{header}}}
      <span class="tt-suggestions">
        {{#suggestions}}
          <div class="tt-suggestion">{{{html}}}</div>
        {{/suggestions}}
      </span>
      {{{footer}}}
    </div>
  {{/dataset}}
</span>

When an end-user mouses or keys over a .tt-suggestion, the class tt-is-under-cursor will be added to it. You can use this class as a hook for styling the "under cursor" state of suggestions.

Browser Support

• Chrome
• Firefox 3.5+
• Safari 4+
• Internet Explorer 7+
• Opera 11+

Issues

Discovered a bug? Please create an issue here on GitHub!

https://github.com/twitter/typeahead.js/issues

Versioning

For transparency and insight into our release cycle, releases will be numbered with the follow format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backwards compatibility bumps the major
• New additions without breaking backwards compatibility bumps the minor
• Bug fixes and misc changes bump the patch

For more information on semantic versioning, please visit http://semver.org/.

Testing

Tests are written using Jasmine. To run the test suite with PhantomJS, run $ grunt test. To run the test suite in your default browser, run $ grunt test:browser.

Developers

If you plan on contributing to typeahead.js, be sure to read the contributing guidelines.

In order to build and test typeahead.js, you'll need to install its dev dependencies ($ npm install) and have grunt-cli installed ($ npm install -g grunt-cli). Below is an overview of the available Grunt tasks that'll be useful in development.

• grunt build – Builds typeahead.js from source.
• grunt lint – Runs source and test files through JSHint.
• grunt test – Runs the test suite with PhantomJS.
• grunt test:browser – Runs the test suite in your default browser.
• grunt watch – Rebuilds typeahead.js whenever a source file is modified.
• grunt server – Serves files from the root of typeahead.js on localhost:8888. Useful for using test/playground.html for debugging/testing.
• grunt dev – Runs grunt watch and grunt server in parallel.

Authors

• Tim Trueman (Twitter / GitHub)
• Veljko Skarich (Twitter / GitHub)
• Jake Harding (Twitter / GitHub)

Shoutouts!

Thanks for assistance and contributions:

• @fat
• @garann
• @paulirish
• @sindresorhus
• @thisguy
• And many others!

License

Copyright 2013 Twitter, Inc.

Licensed under the MIT License