Address picker built with typeahead autocomplete from twitter
JavaScript CoffeeScript HTML CSS
Switch branches/tags
Clone or download
Latest commit f534981 Nov 4, 2015
Failed to load latest commit information.
bower_components add bower_components Jul 17, 2014
demo ue bower for typeahead Feb 11, 2015
dist update to 0.1.4 to make a new bower version Feb 11, 2015
src Bind to typeahead:autocompleted to fire when tab selected Oct 6, 2015
.gitignore add AddressPicker#bindDefaultTypeaheadEvent method Mar 16, 2014
.travis.yml First spec Mar 15, 2014 remove coverage Feb 11, 2015
LICENSE Initial commit Feb 28, 2014 Update Nov 3, 2015
bower.json update to 0.1.4 to make a new bower version Feb 11, 2015
screenshot.png Better README Mar 16, 2014

Typeahead Address Picker Build Status

It's not an extension of typeahead plugin itself, but a new data source for twitter typeahead (version > 0.10.0)

The AddressPicker is a subclass of a Bloodhound class. It connects suggestions to Google Map AutocompleteService.

But it's much more than a simple suggestion engine because it can be linked to a google map to display/edit location.

How to use

Without a Google Map

The simplest usage is to use it as suggestion engine, without displaying results on google map.

  1. Include typeahead and google map with places activated

Using this repository

<script src=""></script>
<script src=""></script>
<script src="../dist/typeahead.js"></script>
<script src="../dist/typeahead-addresspicker.js"></script>

Or if you want to quickly get started

<script src=""></script>
<script src=""></script>
<script src=""></script>
<script src=""></script>
  1. Add an input text
<input id="address" type="text" placeholder="Enter an address">
  1. Instanciate an AddressPicker and a typeahead
var addressPicker = new AddressPicker();

$('#address').typeahead(null, {
  displayKey: 'description',
  source: addressPicker.ttAdapter()

With a Google Map

For a better user experience, you can connect it to a google map to display results. You just need to add a div as for a google map place holder and connect it to the AddressPicker

  1. As before

  2. Add a div

<input id="address" type="text" placeholder="Enter an address">
<div id="map"></div>
  1. Instantiate an AddressPicker with the google map div element or ID and connect typeahead events.
// instantiate the addressPicker suggestion engine (based on bloodhound)
var addressPicker = new AddressPicker({
 map: {
  id: '#map'

// instantiate the typeahead UI
$('#address').typeahead(null, {
  displayKey: 'description',
  source: addressPicker.ttAdapter()

// Bind some event to update map on autocomplete selection
$('#address').bind('typeahead:selected', addressPicker.updateMap);
$('#address').bind('typeahead:cursorchanged', addressPicker.updateMap);


When you instantiate a new AddressPicker you can pass a list of options new AddressPicker(options)

Available Options:

  • map (Hash): Map id and options to link typeahead to a goggle map (default: none).

    • id (String/Element) DOM map element or CSS selector
    • all google.maps.Map constructor options. Default values are:
      zoom: 3,
      center: new google.maps.LatLng(0, 0),
      mapTypeId: google.maps.MapTypeId.ROADMAP
  • marker (Hash): Marker options display on the map.

      draggable: true,
      visible: false,
      position: MAP_CENTER
  • autocompleteService (Hash) : options passed to google.maps.places.AutocompleteService#getPlacePredictions (default: {types: ['geocode']}) For more details read Google documentation. You can add a lot of options, like get only address for a country, or get only cities.

    Example To get only cities in United States:

      autocompleteService: {
        types: ['(cities)'], 
        componentRestrictions: { country: 'US' }
  • zoomForLocation (Number): Zoom value when an accurate address is selected (default: 16).

  • reverseGeocoding (Boolean): Reverse geocoding when marker is dragged on map (default: false).

  • placeDetails (Boolean): If not using with a map, you can skip the getDetails portion to speed up the query (default: false).


Only one event is trigger by AddressPicker object: addresspicker:selected. The event is fired when an address is selected or when the marker is dragged. If reverseGeocoding is activated, a full response is trigger, otherwise only lat/lng.

To simplify google response parsing, we fire an object of type AddressPickerResult with some accessors:

  • lat()
  • lng()
  • addressTypes()
  • addressComponents()
  • nameForType: (type, shortName = false)

Listen that event to get values you need and store them in your form. Here is an example:

// Proxy inputs typeahead events to addressPicker

// Listen for selected places result
$(addressPicker).on('addresspicker:selected', function (event, result) {


The code is tested as much as possible. If you want to add features, please add spec in your pull request.


A demo is included in the github repository, and is available here:

Quick example to show how to use twitter typeahead autocomplete and google map API to make an address picker.

This example is just a first try and could be enhanced to fully replace my previous address picker:

Any suggestions (using issues) or pull requests are welcome.


  • Connect HTML5 geolocalisation API to display user position
  • Anything else that could make sense to be added :). You can open an issue with a label "feature" to open a discussion on a feature/API you'd like to add.


@copyright Sébastien Gruhier / Xilinus ( - -