Google Maps Store Locator Plugin For jQuery

File Size: 294 KB
Views Total: 50336
Last Update:
Publish Date:
Official Website: Go to website
License: MIT
Google Maps Store Locator Plugin For jQuery

This jQuery Plugin helps your company easily create a store locator using Google Maps API. 

Without using any extra back-end programming, you just need to feed it KML, XML, or JSON data with all the location information.

Basic Usage (Using Chipotle as an Example):

1. Include jQuery library and the jQuery Store Locator plugin.

<script src=""></script> 
<script src="js/jquery.storelocator.js"></script> 

2. Include the required handlebars.js and Google Map API V3.

<script src="js/handlebars.min.js"></script> 
<script src=""></script> 

3. Include the plugin's stylesheet.

<link rel="stylesheet" href="css/storelocator.css">

4. The HTML structure.

<div id="map-container">
<div id="loc-list">
<ul id="list">
<div id="map"></div>

5. Call the plugin on the map container.

$(function() {

6. Options and callbacks.

// Allows custom data to be sent with the AJAX request. 
// Set the setting to an object with your properties and values.
'ajaxData'                   : null,

// Display no results message vs. all locations when closest location is further than distanceAlert setting
'altDistanceNoResult'        : false,

// Set to your Google Maps API key when using Lazy Load setting. Value is unused if lazyLoadMap is false.
'apiKey'                     : null,

// Set to true to enable Google Places autocomplete. 
// Note the slight markup differences in the example file.
'autoComplete'               : false,

// Disable the listener that immediately triggers a search when an auto complete location option is selected.
'autoCompleteDisableListener': false,

// Google Places autocomplete options object.
'autoCompleteOptions'        : {},

// Disable displaying markers and location list indicators with alpha characters.
'disableAlphaMarkers'        : false,

// Set to an array of taxonomies that should filter exclusively vs. inclusively.
'exclusiveTax'               : null,

// Set to true to highlight the nearest location automatically after searching.
'openNearest'                : false,

// Set to an object for custom sorting that accepts three properties: method ('alpha', 'date', or 'numeric'), order ('asc', or 'desc'), and prop (property in your data to sort by such as name, city, distance, etc.).
'sortBy'                     : null,

// HTML elements
'addressID'                  : 'bh-sl-address',
'closeIcon'                  : 'bh-sl-close-icon',
'formContainer'              : 'bh-sl-form-container',
'formID'                     : 'bh-sl-user-location',
'geocodeID'                  : null,
'lengthSwapID'               : 'bh-sl-length-swap',
'loadingContainer'           : 'bh-sl-loading',
'locationList'               : 'bh-sl-loc-list',
'mapID'                      : 'bh-sl-map',
'maxDistanceID'              : 'bh-sl-maxdistance',
'modalContent'               : 'bh-sl-modal-content',
'modalWindow'                : 'bh-sl-modal-window',
'overlay'                    : 'bh-sl-overlay',
'regionID'                   : 'bh-sl-region',
'searchID'                   : 'bh-sl-search',
'sortID'                     : 'bh-sl-sort',
'taxonomyFiltersContainer'   : 'bh-sl-filters-container',

// Google maps settings object.
'mapSettings'              : {
  zoom     : 12,
  mapTypeId: google.maps.MapTypeId.ROADMAP

// Marker Clusterer settings object.
'markerCluster'              : null,

// Replacement marker image used for all locations
'markerImg'                : null,

// Replacement marker dimensions object
// ex value: { height: 20, width: 20 }
'markerDim'                : null,

// Multiple replacement marker images based on categories object. 
// Value should be array with image path followed by dimensions.
// ex value: catMarkers : {'Restaurant' : ['img/red-marker.svg', 32, 32]}
'catMarkers'               : null,

// Selected marker image.
'selectedMarkerImg'        : null,

// Selected marker image dimensions object - ex value: { height: 20, width: 20 }
'selectedMarkerImgDim'     : null,

// The unit of length. Default is m for miles.
// Change to km for kilometers.
'lengthUnit'               : 'm',

// The number of closest locations displayed at one time. 
// Set to -1 for unlimited.
'storeLimit'               : 26,

// Displays alert if there are no locations with 60 m/km of the user's location. 
// Set to -1 to disable.
'distanceAlert'            : 60,

// The format of the data source. 
// Accepted values include kml, xml, json, and jsonp.
'dataType'                 : 'xml',

// Accepts raw KML, XML, or JSON instead of using a remote file.
'dataRaw'                  : null,

// The path to the location data.
'dataLocation'             : 'data/locations.xml',

// XML element used for locations (tag).
'xmlElement'               : 'marker',

// Background color of the odd list elements.
'listColor1'               : '#ffffff',

// Background color of the even list elements.
'listColor2'               : '#eeeeee',

// Display a marker at the origin.
'originMarker'             : false,

// Replacement origin marker image.
'originMarkerImg'          : null,

// Replacement origin marker dimensions object
// ex value: { height: 20, width: 20 }
'originMarkerDim'          : null,

// Bounces the maker when a list element is clicked.
'bounceMarker'             : true,

// First hides the map container and then uses jQuery’s slideDown method to reveal the map.
'slideMap'                 : true,

// Shows the map container within a modal window. 
// Set slideMap to false and this option to true to use.
'modal'                    : false,

// Modal selectors.
'overlay'                  : 'bh-sl-overlay',
'modalWindow'              : 'bh-sl-modal-window',
'modalContent'             : 'bh-sl-modal-content',
'closeIcon'                : 'bh-sl-close-icon',

// If true, the map will load with a default location immediately. 
// Set slideMap to false if you want to use this.
'defaultLoc'               : false,

// If using defaultLoc, set this to the default location latitude.
'defaultLat'               : null,

// If using defaultLoc, set this to the default location longitude.
'defaultLng'               : null,

// Set to true if you want to use the HTML5 geolocation API (good for mobile) to geocode the user's location.
'autoGeocode'              : false,

// Set to true if you want to give users an option to limit the distance from their location to the markers.
'maxDistance'              : false,

// ID of the select element for the maximum distance options.
'maxDistanceID'            : 'bh-sl-maxdistance',

// Set to true if you want to immediately show a map of all locations. 
// The map will center and zoom automatically.
'fullMapStart'             : false,

// Set to a zoom integer if you want to immediately show a blank map without any locations.
'fullMapStartBlank'        : false,

// Set to a number to limit the number of items displayed in the location list with full map start.
'fullMapStartListLimit'      : false,

// InfoBubble settings object. 
'infoBubble'                 : null,

// Set to true if you aren't able to use form tags ( WebForms).
'noForm'                   : false,

// Set to true to display a loading animated gif next to the submit button.
'loading'                  : false,

// Class of element container that displays the loading animated gif.
'loadingContainer'         : 'bh-sl-loading',

// restrict featured locations by a specified distance
'featuredDistance'           : null,

// Set to true to enable featuring locations at the top of the location list (no matter the distance).
// Add featured=”true” to featured locations in your XML or JSON locations data.
'featuredLocations'        : false,

// Set to true to enable displaying location results in multiple "pages."
'pagination'               : false,

// If using pagination, the number of locations to display per page.
'locationsPerPage'         : 10,

// Set to true to enable displaying directions within the app instead of an off-site link.
'inlineDirections'         : false,

// Set to true to lazy load the Google Maps API script. 
// Make sure to also set the apiKey setting and do not include the script manually.
'lazyLoadMap'              : false,

// Set to true to allow searching for locations by name using separate searchID field.
'nameSearch'               : false,

// ID of the search input form field for location name searching.
'searchID'                 : 'bh-sl-search',

// If using nameSearch, the data attribute used for the location name in the data file.
'nameAttribute'            : 'name',

// Set to true to have the location list only show data from markers that are visible on the map.
'visibleMarkersList'       : false,

// Set to true to perform a new search after the map is dragged.
'dragSearch'               : false,

// Template paths
'infowindowTemplatePath'   : 'assets/js/plugins/storeLocator/templates/infowindow-description.html',
'listTemplatePath'         : 'assets/js/plugins/storeLocator/templates/location-list-description.html',
'KMLinfowindowTemplatePath': 'assets/js/plugins/storeLocator/templates/kml-infowindow-description.html',
'KMLlistTemplatePath'      : 'assets/js/plugins/storeLocator/templates/kml-location-list-description.html',

// ID of list template if using inline Handlebar templates instead of separate files.
'listTemplateID'           : null,

// ID of infowindow template if using inline Handlebar templates instead of separate files.
'infowindowTemplateID'     : null,

// Filtering object that can be used to set up live filtering
'taxonomyFilters'          : null,

// Class of the container around the filters.
'taxonomyFiltersContainer' : 'bh-sl-filters-container',

// Set to true to enable exclusive taxonomy filtering rather than the default inclusive.
'exclusiveFiltering'       : false,

// Set to true to enable query string support for passing input variables from page to page.
'querystringParams'        : false,

// Store user's location when autoGeocode in enabled to prevent multiple lookups per session.
'sessionStorage'           : false,

// Callbacks
'callbackAutoGeoSuccess'     : null,
'callbackBeforeSend'         : null,
'callbackCloseDirections'    : null,
'callbackCreateMarker'       : null,
'callbackDirectionsRequest'  : null,
'callbackFilters'            : null,
'callbackFormVals'           : null,
'callbackGeocodeRestrictions': null,
'callbackJsonp'              : null,
'callbackListClick'          : null,
'callbackMapSet'             : null,
'callbackMarkerClick'        : null,
'callbackModalClose'         : null,
'callbackModalOpen'          : null,
'callbackModalReady'         : null,
'callbackNearestLoc'         : null,
'callbackNoResults'          : null,
'callbackNotify'             : null,
'callbackPageChange'         : null,
'callbackRegion'             : null,
'callbackSorting'            : null,
'callbackSuccess'            : null,

// Language options
'addressErrorAlert'          : 'Unable to find address',
'autoGeocodeErrorAlert'      : 'Automatic location detection failed. Please fill in your address or zip code.',
'distanceErrorAlert'         : 'Unfortunately, our closest location is more than ',
'kilometerLang'              : 'kilometer',
'kilometersLang'             : 'kilometers',
'mileLang'                   : 'mile',
'milesLang'                  : 'miles',
'noResultsTitle'             : 'No results',
'noResultsDesc'              : 'No locations were found with the given criteria. Please modify your selections or input.',
'nextPage'                   : 'Next &raquo;',
'prevPage'                   : '&laquo; Prev'

More Examples:


v3.4.0 (2024-05-19)

  • Added support for new Map ID with mapSettingsID setting. Please refer to Use Map IDs and Map ID with Styling in the Google API docs.
  • Added support for new Advanced Markers while maintaining support for the deprecated (not yet discontinued) marker functionality. mapSettingsID setting needs to be set and marker library needs to be included - see previous item.
  • Fixed bugs with pagination.
  • Fixed new "Google Maps JavaScript API has been loaded directly without loading=async" notice.
  • Improved pagination accessibility and functionality.

v3.3.0 (2023-12-11)

  • Updated max distance functionality to make distance changes apply dynamically vs. having to manually click button.

v3.2.1 (2023-11-13)

  • Swapped old API domain to in all example files.

v3.2.0 (2023-10-02)

  • Added new Google Maps lazy load setting and example file - see new lazyLoadMap and apiKey settings.

v3.1.14 (2023-08-10)

  • Fix - reverted removal of zoom reset to 0 after taxonomy filtering due to introduction of new issue.

v3.1.13 (2023-07-26)

  • Fixed additional disable filtering functionality related to select options and radio buttons by globally tracking the disabled values.
  • Removed zoom reset to zero on taxonomy filtering to keep searched location in view.
  • Updated maybeDisableFilterOptions to run when full map start or default location settings are enabled.

v3.1.10 (2023-02-20)

  • Added map marker accessibility.
  • Deprecated bounceMarker setting due to Google Charts API deprecation and poor animation results with Google marker labels.
  • Fixed issue with new disable filtering functionality when location objet property is missing.
  • Fixed marker labels not working with previous technique. Swapped to google.maps.Marker label parameter.
  • Updated package devDependencies.

v3.1.9 (2023-02-06)

  • Added functionality to disable input and option fields that don't have matching values in the current location set after filtering when inclusive filtering is used (default).
  • Extended nameAttribute settings so multiple attributes can be searched. Separate attribute names with commas.
  • Fixed location set length scenario when fullMapStart is enabled and taxFilters is reset and name search and origin are empty.
  • Show empty result message if no locations with default sorting.
  • Temporary fix for missing Google Maps callback parameter console error - the parameter requirement was not previously enforced on the API side.
  • Updated deprecated google.maps.event.addDomListener usage with window.addEventListener.

v3.1.8 (2022-08-22)

  • Added coordinate range check to exclude locations with invalid latitude and longitude values.

v3.1.7 (2022-06-27)

  • Fixed empty name search value not clearing previous value.
  • Fixed openNearest setting not working in combination with querystringParams setting.
  • Fixed openNearest setting not opening correct location with custom sorting (sortBy) enabled.

v3.1.6 (2021-12-06)

  • Fixed empty name search value not clearing previous value.
  • Fixed openNearest setting not working in combination with querystringParams setting.
  • Fixed openNearest setting not opening correct location with custom sorting (sortBy) enabled.

v3.1.5 (2021-09-30)

  • Added extra check to make sure mapping doesn't fire twice when defaultLoc is enabled and fullMapStart is also enabled.
  • fullMapStart is not needed when defaultLoc is enabled and this is just a preventative to avoid user errors.
  • Fixed centering issue on initial search with maxDistance enabled introduced with fitBounds updates in last update.

v3.1.4 (2021-06-07)

  • Fixed name search filter value not clearing if form input is cleared

v3.1.3 (2021-05-09)

  • Fixed empty name search field value overriding filter results.
  • Fixed groups of filters not applying together.
  • Fixed potential error from occurring if fullMapStartListLimit is set, and the number of locations is less than the limit.
  • Updated bundled Handlebars to v4.7.7

v3.1.1 (2020-01-10)

  • Enhanced filtering regular expression to better account for exact matches vs. substrings.
  • Fixed multi-category selection filtering issue introduced in last version 3.1.0.
  • Updated bundled Handlebars to v4.7.6.
  • Updated node modules.

v3.1.0 (2019-11-18)

  • Added featuredDistance setting to restrict featured locations by a specified distance (number value should be used).
  • Updated bundled version of Handlebars to v4.5.1 due to security issue.
  • Updated taxonomy filtering REGEX and string replacements for international character support.

v3.0.0 (2018-09-30)

  • Added ajaxData to allow custom data to be sent with the AJAX request. The setting accepts an object.
  • Added altDistanceNoResult setting to display no results message vs. all locations when closest location is further than distanceAlert setting.
  • Added callbackAutoGeoSuccess callback that fires after the geolocation API returns a successful result.
  • Added callbackFormVals callback that fires after the form values have been processed from the form.
  • Added callbackGeocodeRestrictions callback that allows the componentRestrictions object to be overridden.
  • Added callbackNearestLoc callback that fires when the nearest location is triggered with the openNearest setting.
  • Added callbackSorting callback that fires when when a new sorting method is selected.
  • Added component filtering for geocoding to better restrict by area.
  • Added length unit (distance miles/kilometers) front-end swap functionality, setting and example file.
  • Added mappingObject, originPoint, data, and page parameters to callbackSuccess callback.
  • Added new front-end sorting functionality, settings, and example file.
  • Added location data object as parameter of callbackDirectionsRequest callback.
  • Added openNearest setting to open/select the nearest location after searching.
  • Fixed issue with featuredLocations setting where featured locations at far distances would trigger distance alert.
  • Fixed issue with filtering values containing ampersands, which would not display any results - updated filtering regex.
  • Fixed issue where HTML5 Geolocation was skipped when using the fullMapStartBlank setting.
  • Fixed issue with pagination page numbers displaying after no results via PR from heldr88
  • Fixed issue with taxonomy filtering and autoGeocode setting where HTML Geocoding API would run on every filter change.
  • Removed Less from the project as it is no longer needed with the Bootstrap update.
  • Swapped the default location data type to be JSON instead of XML.
  • Updated Bootstrap example file to make use of Bootstrap 4.
  • Updated taxonomy filtering so pagination is reset to first page after selecting a filter.
  • Fixed issue with mapReload (triggered with optional reset button) where storeLimit wasn't reset


  • Fixed error when filtering with query strings where filter values with spaces wouldn't work, updated processForm method so submitting the map removes focus from any of the form input/select fields instead of just the address input, updated filterData string replace methods to match string replace method in filters setup


  • Added autoCompleteDisableListener setting to disable the listener that immediately triggers a search when an auto complete location option is selected, fixed Handlebars targeting issue triggered by placing an unordered list within the location list template


  • Added callbackRegion callback, which allows region to be set before being sent to the Google Maps Geocoding API


  • Hotfix to prevent potential error with updated filterData method if the category of a location is undefined, missed updating version in package.json file


  • Added checks to replace non-ASCII characters when filtering, removed non-standard $1 RegExp property in processData method, updated version


  • Added callbackMapSet callback that fires after the map has been set up, fixed issue where locations without attributes could get those attribute values from prior locations
  • Fixed issue where pagination total number of pages was based on the full location set total instead of the storeLimit setting


  • Fixed issue with new boundary search AJAX params after a full address search was made

v2.5.3 (2016-04-04)

  • Re-worked handling of no results

v2.5.2 (2016-03-17)

  • Fixed pagination bubbling issue, Fixed pagination issues with autoGeo code and dragSearch combinations

v2.5.1 (2016-03-13)

  • Fixed issues with visibleMarkersList and location list background colors and selection.

v2.5.0 (2016-03-06)

  • Added new dragSearch setting which peforms a new search when the map is dragged when enabled.
  • Added new geocodeID setting so that the HTML geocoding API can be triggered by a button instead of firing automatically.
  • Fixed issues with no results where clicking the marker would display data from the previous result and clicking the location list item would throw an error.
  • Merged in pull request from hawkmeister with update to bower.json file with main property.
  • Merged in pull request from hyperTwitch with fixes for using fullMapStartListLimit in combination with a different store limit.
  • Updated jQuery references to the latest version.

v2.4.1 (2016-01-21)

  • Changed new full map start list limit so that it's only applied on the initial load.
  • Fixed issue with new autocomplete setting where search was firing twice.
  • Added new selected marker image options to highlight clicked marker.
  • Added Google Places autocomplete option and example file.
  • Added full map start location list limit setting.
  • Fixed issue with settings combination of inline directions and default location

v2.3.3 (2015-12-23)

  • Removed hide map and results when there are no results in favor of just displaying the no results message and empty map
  • Added fullMapStartBlank option and example

v2.2.4 (2015-12-15)

  • Tweaked list label width styling.

v2.2.3 (2015-12-13)

  • Added preventative styling to inline directions panel table, switched to unitless line-heights

v2.2.2 (2015-12-01)

  • Added preventative styling to avoid table conflicts with directions panel, fixed clearMarkers bug with inline directions enabled

v2.2.1 (2015-11-28)

  • Updated preventative styling to be more specific to the map container and added max-height img rule.

v2.2.0 (2015-11-22)

  • Added check for Google Maps API.
  • Added Grunt Handlebars task for compiling Handlebars templates from src directory - will add more compatibility in future release.
  • Added preventative styling to avoid conflicts with CSS frameworks and resets.
  • Default design refresh.
  • Fixed bug with inline directions panel that occurred after multiple address submissions.
  • Removed sensor parameter from Google Maps API URL as it's no longer needed.
  • Switched the default plugin styling from LESS to SASS.
  • Updated included Handlebars to v4.0.5.

v2.1.0 (2015-09-20)

  • Added ability to pass in array object as dataRaw.
  • Added writeDebug console.log helper function for debugging.
  • Added sessionStorage option to store user's location when autoGeocode in enabled to prevent multiple lookups per session.
  • Fixed bug with inline directions panel that occurred after multiple address submissions.
  • Updated processForm method form field variables with empty string fallback values.

v2.0.9 (2015-08-14)

  • Fixed issue when using catMarkers setting and not setting a location's category resulted in an error.

v2.0.8 (2015-07-20)

  • Changed infowindow and location list templates so that the comma is added if the city is available.
  • Fixed issue with inline directions where "null" was prepended to the destination address.
  • Fixed close directions bug where close icon couldn't be clicked more than two times.
  • Fixed bug where form wasn't overriding query string parameters.
  • Updated processForm method to accept max distance query string parameter.
  • Updated processForm method to use existing origin data if it's present and matches to avoid unnecessary geocode requests.
  • Updated max distance check to less than or equal to the selected distance vs. just less than.
  • Updated regionID description in for clarity.
  • Updated formEventHandler method to prevent form submission on keydown instead of keyup.
  • Updated mapSettings description in to highlight that zoom can be set to 0 for automatic centering and zooming.

v2.0.7 (2015-04-03)

  • Fixed bug where reverse geocoding wasn't passing the origin to the templates (autogeocode and default location), causing incorrect direction links.
  • Updated location list directions link to use https.
  • Added the option to filter data exclusively rather than inclusively with the exclusiveFiltering setting.
  • Added callbackFilters that fires when a filter is changed and returns the filter values if needed.
  • Added dataRaw option to use raw KML, XML or JSON data instead of the AJAX call.
  • Added basic raw data example rawdata-example.php file.
  • Added visibleMarkersList option that updates the location list to only display data from the markers that are curently displayed on the map.
  • Changed the distance error functionality so that the map centers and zooms automatically and all locations are displayed on the map.
  • Fixed issue with fullMapStart and inlineDirections setting combination.
  • Fixed issue with global olat and olng variables not being set with autoGeocode setting enabled.
  • Fixed issue with maxDistance and autoGeocode setting combination.

v2.0.5 (2015-01-05)

  • Fixed typo with originMarker setup.
  • Made the originMarkerDim setting optional when setting a custom origin marker image - defaults to 32px by 32px.
  • Removed geocodeErrorAlert language option and switched error alerts to custom exceptions so users aren't shown multiple alerts.
  • Fixed bug with inline directions where close icon wasn't being removed on page reload.
  • Added callbackListClick that fires when a list element is clicked.
  • Added callbackMarkerClick that fires when a map marker is clicked.

v2.0.4 (2014-12-16)

  • Fixed bug with maxDistance and pagination setting combination. The last page of of the pagination results was set to use the locationsPerPage setting instead of the remaining number, which could have resulted in the plugin trying to load undefined locations.
  • Fixed bugs with googleGeocode and reverseGoogleGeocode methods in which references to "this" were undefined.

v2.0.3 (2014-12-12)

  • Fixed bug with maxDistance setting - updated locationsSetup method so that the locationset array uses array.push instead of incrementing via a passed in parameter, which was causing undefined array elements and causing errors.
  • Removed testing line from maxdistance-example.html that was left in.

v2.0.2 (2014-12-08)

  • Updated the Handlebars.compile calls when using the inline template options to include the ID hash so that it's consistent with the other ID settings.
  • Fixed incorrect callback call in the modalClose method - callbackModalOpen to callbackModalClose.
  • Added callbackModalReady that fires when the the content of the modal is generated.
  • Fixed markerImg setting - previously threw error if markerDim wasn't set.

v2.0.0 (2014-11-03)

  • Complete rewrite.
  • Many of the methods are public and can be called as needed
  • Google Maps settings are now exposed as a setting. Instead of trying to modify the plugin to make Google Maps settings changes simply use the mapSettings option to override.
  • Added inline directions option
  • Added multi-group live filtering via regex for quick category, etc. filtering.
  • Added option to search locations by name
  • Added option to set custom markers by category
  • Added option for paginating results
  • Added responsive Bootstrap example
  • Added region biasing setting to handle region/country select field
  • Added coordinates and address (user input) to primary AJAX GET request for better back-end integration
  • Added option to check for query string parameters

v1.4.9 (2013-09-06)

  • Store the map object into the jQuery object in order to retrieve it by calling $'map').
  • Possibility to add custom variables in locations
  • If 'distance' variable is set in location, do not calculate it
  • Enabling the new Google Maps
  • Replaced submit image button image with button tag and CSS3
  • Overrode new infowindow Roboto font for consistent style
  • Removed icon shadows because they are no longer work in the upcoming version of Google Maps: see
  • Changed "locname" to "name" for each location in the JSON file to match other location data types and to avoid renaming
  • Simplified some parts of the code

v1.4.8 (2013-07-15)

  • Added the possibility to set the 'storeLimit' option to -1, which means unlimited
  • Added the possibility to set the 'distanceAlert' option to -1, which means disable distance alert
  • Added little checks to only format 'web' variable when it is not null otherwise javascript would gives an error
  • Possibility to add custom variables in locations
  • If 'distance' variable is set in location, do not calculate it
  • Simplified some parts of the code
  • If noForm is true, only simulate the submit when the field is actually in focus


This awesome jQuery plugin is developed by bjorn2404. For more Advanced Usages, please check the demo page or visit the official website.