jQuery Geocomplete
A jQuery plugin for Google Maps Autocomplete.
View Demo »
Table of contents
Quick start
- Download the latest release
- Clone the repo:
git clone https://github.com/tmentink/jquery.geocomplete.git
Both the compiled and minified versions can be found within the dist/ directory:
jquery.geocomplete/
└── dist/
├── jquery.geocomplete.js
├── jquery.geocomplete.min.css
└── jquery.geocomplete.min.js
Basic usage
Setup the appropriate HTML ensuring that your form has an id and that you've added the data attributes to all the inputs you want to autocomplete.
The data attribute will be used to lookup the value once a place has been selected. The order of the lookup is as follow:
- name of a function located in $.fn.geocomplete.settings.formats
- name of a PlaceResult property
- name/alias of an address type
Capitalization, spaces and underscores do not affect any internal lookups
<div id="myForm">
<input id="myInput" data-geocomplete="street address" />
<select data-geocomplete="country"></select>
<input data-geocomplete="formatted phone number" />
...
</div>Then simply select the main input and call .geocomplete() with the id of the form
$("#myInput").geocomplete({
formId: "myForm"
})You can also use it to center a map based on the selected location.
var myMap = new google.maps.Map(document.getElementById("myMap"), {
center : { lat: 37.5, lng: -120 },
zoom : 6
});
$("#myInput").geocomplete({
map: myMap
})Documentation
Settings
You can set the defaults at $.fn.geocomplete.settings
| Setting | Type | Default | Description |
|---|---|---|---|
| appendToParent | boolean | true | Appends the autogenerated .pac-container to the selected input's parent. This fixes the scrolling issue |
| bounds | LatLngBounds | undefined | Google's Documentation |
| componentRestrictions | object | undefined | Google's Documentation |
| fields | Array<string> | undefined | Google's Documentation |
| formats | string | Object | An object containing functions that can be called to format custom results. The function is passed the PlaceResult class and must return a String. Geocomplete will look for these first before searching for properties then finally address components |
| formId | string | undefined | The id of the form containing the inputs to be autocomplete |
| geolocate | boolean | false | Sets the bounds based on the browser's location. Used to bias the search results to a specific area |
| inputDataKey | string | geocomplete | The name of the data attribute used to autocomplete inputs. Do not prefix with data- |
| map | google.maps.Map | undefined | The google map you would like to center based upon the selected location |
| strictBounds | boolean | false | Google's Documentation |
| types | Array<string> | undefined | Google's Documentation |
Callbacks
| Callback | Context | Description |
|---|---|---|
| onChange(name, result) | $selector | Is called after a place is changed. Recieves the name and the place results |
| onNoResult(name) | $selector | Is called after a place is changed but no result was found. Recieves the name that was entered |
Address Types
You can access the short_name value by addding "short" in front of the type. Otherwise it will return the long_name value. Below is a list of all the aliases. You can find the full list of address types here
| Type | Google Equivalent |
|---|---|
| city | locality |
| county | administrative_area_level_2 |
| state | administrative_area_level_1 |
| street | route |
| zip code | postal_code |
| zip code suffix | postal_code_suffix |
Methods
All the following methods can be called using the syntax:
$("#myInput").geocomplete("method name", arguments)| Method | Arguments | Returns | Description |
|---|---|---|---|
| center map | LatLng | LatLngBounds | $selector | Centers the map based on the supplied LatLng or LatLngBounds. If nothing is passed, it will use the last selected location. This is automatically called when a location is selected. |
| clear form | none | $selector | Clears all the inputs inside the form. This is automatically called before filling the form. |
| fill form | PlaceResult | none | $selector | Fills all the inputs based on the supplied PlaceResult or the last selected location. This is automatically called when a location is selected. |
| get bounds | none | LatLngBounds | Google's Documentation |
| get cached place | none | PlaceResult | Returns the last PlaceResult that was retrieved. The get place method will result in an additional API call |
| get fields | none | Array<string> | Google's Documentation |
| get form values | string | none | Object | Any | Returns an object containing the form values from the last selected location. You can optionally supply a query to return a specific value |
| get place | none | PlaceResult | Google's Documentation |
| set bounds | LatLngBounds | $selector | Google's Documentation |
| set component restrictions | Object | $selector | Google's Documentation |
| set fields | Array<string> | $selector | Google's Documentation |
| set options | Object | $selector | Google's Documentation |
| set types | Array<string> | $selector | Google's Documentation |
Credits
- The jQuery Team - for creating jQuery
- Google - for creating Google Maps
Author
Trent Mentink
Copyright and license
- Code and documentation copyright 2017-2019 Trent Mentink.
- Code released under the MIT License.