Backbone.Typeahead

A Bootstrap inspired Typeahead for Backbone.js

Install

The typeahead can be installed with Bower:

bower install backbone.typeahead

or NPM:

npm install backbone.typeahead.js

This project targets Backbone 1.1.0 and above using Bootstrap 3. If you need 1.0.0 support, check out the v0.1.0 release of the typeahead. For an example using the old Bootstrap styles, see docs/bootstrap2.html.

Quickstart

To quickly create a typeahead, provide the the constructor with an array of objects to be searched. By default, the typeahead will search the key name.

var queryset = [
    {name: 'Super Bass-O-Matic 1976'},
    {name: 'Jam Hawkers'},
    {name: 'HiberNol'},
    {name: 'Colon Blow'},
];

var typeahead = new Backbone.Typeahead(queryset);
$('#main').html(typeahead.render().el);

The typeahead also plays nice with setElement:

typeahead.setElement('#main').render();

The typeahead will emit a selected event when the user selects an item. The selected model is accessible as the first parameter of the callback:

typeahead.on('selected', function(model) {
    console.log('The user has selected:', model);
});

Passing a Collection

The typeahead is built upon a Backbone.View and accepts a Backbone.Collection as the option collection:

var queryset = [
    {name: 'Super Bass-O-Matic 1976'},
    {name: 'Jam Hawkers'},
    {name: 'HiberNol'},
    {name: 'Colon Blow'},
];
var products = new Backbone.Collection(queryset);

var typeahead = new Backbone.Typeahead({collection: products});
typeahead.setElement('#main').render();

Options

Pass the option key to search by a different attribute:

var queryset = [
    {label: 'Super Bass-O-Matic 1976', year: 1976},
    {label: 'Jam Hawkers', year: 1977},
    {label: 'HiberNol', year: 1988},
    {label: 'Colon Blow', year: 1983},
];

var typeahead = new Backbone.Typeahead(queryset, {key: 'label'});
$('#main').html(typeahead.render().el);

Pass the option itemTemplate to render the search results with a different template:

var itemTemplate = '<a><strong><%- label %></strong> (<%- year %>)</a>';
var typeahead = new Backbone.Typeahead(queryset, {key: 'label', itemTemplate: itemTemplate});
$('#main').html(typeahead.render().el);

Using a Different Template

To use a different template for the typeahead itself, I recommend extending the Typeahead object:

var Extended = Backbone.Typeahead.extend({
  template: '<input type="text" class="form-control" placeholder="Find a State!"><ul class="dropdown-menu"></ul>',
});

If the new template has variables, the render method must also be extended:

var Extended = Backbone.Typeahead.extend({
  template: _.template('<input type="text" class="form-control" placeholder="<%- placeholder %>" /><ul class="dropdown-menu"></ul>'),
  render: function() {
    this.$el.html(this.template({
      placeholder: 'Hello, I am a placeholder!'
    }));

    // Don't forget these!
    this.$menu = this.$('ul');
    this.$input = this.$('input');
    return this;
  }
});

Extension

The typeahead was built for easy extension. Check out docs and spec for examples.

Minification

A minified version and source map are provided. Minification was performed with UglifyJS2 using the command:

uglifyjs backbone.typeahead.js -o backbone.typeahead.min.js --source-map backbone.typeahead.min.js.map -c -m

aodin, 2013-2015