Have ideas to improve npm?Join in the discussion! »


1.0.240 • Public • Published

Project status

npm version downloads build status code coverage dependencies development dependencies peer dependencies documentation website

Use case

A webcomponent to serve a store locator via google maps.




Classical dom injection

You can simply download the compiled version as zip file here and inject it after needed dependencies:


<script src="https://code.jquery.com/jquery-3.1.1.min.js"></script>
<script src="https://goo.gl/HEL97d"></script>
<script src="https://cdn.rawgit.com/googlemaps/js-marker-clusterer/gh-pages/src/markerclusterer.js"></script>
<!--Inject downloaded file:-->
<script src="index.compiled.js"></script>
<!--Or integrate via cdn:
<script src="https://goo.gl/s6wRPb"></script>

The compiled bundle supports AMD, commonjs, commonjs2 and variable injection into given context (UMD) as export format: You can use a module bundler if you want.

Package managed and module bundled

If you are using npm as package manager you can simply add this tool to your package.json as dependency:


"dependencies": {
    "storelocator": "latest",

After updating your packages you can simply depend on this script and let a module bundler do the hard stuff or access it via an exported variable name in given context.


import StoreLocator from 'storelocator'
class SpecialStoreLocator extends StoreLocator...
// or
import {$} from 'storelocator'
class SpecialStoreLocator extends $.StoreLocator.class ...
// or
StoreLocator = require('storelocator').default
value instanceof StoreLocator
// or
$ = require('storelocator').$


Adding some style to our store locator examples


body.documentation simple-store-locator,
body.documentation advanced-store-locator,
body.documentation div.store-locator-with-bounds {
    width: 100%;
    height: 400px;
    margin: 0px;
    padding: 0px
body.documentation simple-store-locator > div,
body.documentation advanced-store-locator > div,
body.documentation div.store-locator-with-bounds > div {
    height: 100%;
body.documentation simple-store-locator input.form-control,
body.documentation advanced-store-locator input.form-control,
body.documentation div.store-locator-with-bounds input.form-control {
    margin-top: 9px;
    margin-left: 9px;
    width: 230px;
body.documentation simple-store-locator div.gm-style-iw > div,
body.documentation advanced-store-locator div.gm-style-iw > div,
body.documentation div.store-locator-with-bounds div.gm-style-iw > div {
    width: 225px;
    height: 60px;
    padding: 5px;

Load needed dependencies


const dependenciesLoadPromise = $documentationWebsite.getScript(
).then(() => $.getScript('https://goo.gl/HEL97d')).then(() => $.getScript(
    'https://cdn.rawgit.com/googlemaps/js-marker-clusterer/gh-pages/src/' +
)).then(() => $.getScript('https://goo.gl/s6wRPb'))

Simple example


    dependenciesLoadPromise.always(() => $(
        'body simple-store-locator'
    ).StoreLocator({applicationInterface: {
        // NOTE: You should use your own google maps application interface
        // key.
        key: 'AIzaSyBAoKgqF4XaDblkRP4-94BITpUKzB767LQ'
<simple-store-locator><input class="form-control"></simple-store-locator>

Advanced example with all available (default) options


    dependenciesLoadPromise.always(() => $(
        'body advanced-store-locator'
        applicationInterface: {
                'https://maps.googleapis.com/maps/api/js' +
                '?{1}v=3&sensor=false&libraries=places,geometry&' +
            callbackName: null,
            // NOTE: You should use your own google maps application
            // interface key.
            key: 'AIzaSyBAoKgqF4XaDblkRP4-94BITpUKzB767LQ'
        stores: {
            northEast: {latitude: 85, longitude: 180},
            southWest: {latitude: -85, longitude: -180},
            number: 100,
            generateProperties: (store) => store
        addtionalStoreProperties: {},
        iconPath: '/webAsset/image/storeLocator/',
        defaultMarkerIconFileName: null,
        startLocation: null,
        fallbackLocation: {latitude: 51.124213, longitude: 10.147705},
        ip: null,
        ipToLocation: {
            applicationInterfaceURL: '{1}://freegeoip.net/json/{2}',
            timeoutInMilliseconds: 5000,
            bounds: {
                northEast: {latitude: 85, longitude: 180},
                southWest: {latitude: -85, longitude: -180}
        map: {zoom: 3},
        showInputAfterLoadedDelayInMilliseconds: 500,
        input: {
            hide: {opacity: 0},
            showAnimation: [{opacity: 1}, {duration: 'fast'}]
        distanceToMoveByDuplicatedEntries: 0.0001,
        marker: {
            cluster: {
                gridSize: 100, maxZoom: 11, imagePath:
                    'https://cdn.rawgit.com/googlemaps/' +
            icon: {
                size: {width: 44, height: 49, unit: 'px'},
                scaledSize: {width: 44, height: 49, unit: 'px'}
        successfulSearchZoom: 12,
        infoWindow: {
            content: null,
            additionalMoveToBottomInPixel: 120,
            loadingContent: '<div class="idle">loading...</div>'
        searchBox: 50,
        onInfoWindowOpen: $.noop,
        onInfoWindowOpened: $.noop,
        onAddSearchResults: $.noop,
        onRemoveSearchResults: $.noop,
        onOpenSearchResults: $.noop,
        onCloseSearchResults: $.noop,
        onMarkerHighlighted: $.noop
    <input class="form-control">

Example with limited traversable area (Germany)


    dependenciesLoadPromise.always(() => {
        const bounds = {
            northEast: {latitude: 55.12, longitude: 14.89},
            southWest: {latitude: 47.32, longitude: 5.50}
        $('body div.store-locator-with-bounds').StoreLocator({
            applicationInterface: {
                // NOTE: You should use your own google maps applciation
                // interface key.
                key: 'AIzaSyBAoKgqF4XaDblkRP4-94BITpUKzB767LQ'
            ipToLocation: {bounds},
            limit: {zoom: {minimum: 5}, bounds},
            map: {zoom: 5},
            stores: bounds
<div class="store-locator-with-bounds"><input class="form-control"></div>


  • @property _options.applicationInterface - To store application interface
  • options in.
  • @property _options.applicationInterface.url - URL tor retrieve google maps
  • application interface.
  • @property _options.applicationInterface.callbackName - Global resource path
  • to callback function to trigger when google has finished loading the
  • application interface.
  • @property _options.applicationInterface.key - Application interface key to
  • authenticate against google maps application interface.
  • @property _options.stores - URL to retrieve stores, list of stores or object
  • describing bounds to create random stores within. If a "generateProperties"
  • function is given it will be called to retrieve additional properties for
  • each store. The specified store will be given to the function.
  • @property _options.additionalStoreProperties - Additional static store
  • properties which will be available to each store.
  • @property _options.iconPath - Path prefix to search for marker icons.
  • @property _options.defaultMarkerIconFileName - Specifies a fallback marker
  • icon (if no store specific icon was set). If set to "null" google will place
  • a fallback icon.
  • @property _options.startLocation - If not provided we initialize the map
  • with center in current location determined by internet protocol address. If
  • an object is given a "latitude" and "longitude" with a saved float are
  • assumed.
  • @property _options.fallbackLocation - Fallback location if automatic
  • location determination has failed.
  • @property _options.fallbackLocation.latitude - Latitude value.
  • @property _options.fallbackLocation.longitude - Longitude value.
  • @property _options.ip - If provided given ip will be used to determine
  • current location instead of automatically determined one.
  • @property _options.ipToLocationApplicationInterface - Configuration for ip
  • to location conversion.
  • @property _options.ipToLocationApplicationInterface.bounds - Defines bounds
  • within determined locations should be. If resolved location isn't within
  • this location it will be ignored.
  • @property _options.ipToLocationApplicationInterface.bounds.northEast -
  • Defines north east bound.
  • @property _options.ipToLocationApplicationInterface.bounds.northEast
  • .latitude - North east latitude bond.
  • @property _options.ipToLocationApplicationInterface.bounds.northEast
  • .longitude - North east longitude bond.
  • @property _options.ipToLocationApplicationInterface.bounds.southWest -
  • Defined south west bound.
  • @property _options.ipToLocationApplicationInterface.bounds.southWest
  • .latitude - South east latitude bound.
  • @property _options.ipToLocationApplicationInterface.bounds.southWest
  • .longitude - South west longitude bound.
  • @property _options.ipToLocationApplicationInterface.key - Key to let the api
  • identify your service plan.
  • @property _options.ipToLocationApplicationInterface.protocol - Protocol to
  • use for api requests.
  • @property _options.ipToLocationApplicationInterface.timeoutInMilliseconds -
  • Time to wait for ip resolve. If time is up initialize on given fallback
  • location.
  • @property _options.ipToLocationApplicationInterface.url - IP to location
  • determination application interface url. {1}, {2} and {3} represents
  • currently used protocol, key and potentially given ip.
  • @property _options.map - Initial view properties.
  • @property _options.showInputAfterLoadedDelayInMilliseconds - Delay before we
  • show search input field.
  • @property _options.inputFadeInOption - Transition options to show search
  • input field.
  • @property _options.distanceToMoveByDuplicatedEntries - Distance to move if
  • stores are determined with same latitude and longitude.
  • @property _options.marker - Options passed to the marker cluster. If set to
  • "null" no marker cluster will appear.
  • @property _options.icon - Options passed to the icon.
  • @property _options.successfulSearchZoomLevel - Specifies a zoom value wich
  • will be adjusted after successfully picked a search result. If set to "null"
  • no zoom change happens.
  • @property _options.infoWindow - Info window options.
  • @property _options.infoWindow.content - Function or string returning or
  • representing the info box. If a function is given and a promise is returned
  • the info box will be filled with the given loading content and updated with
  • the resolved data. The function becomes the corresponding marker as first
  • argument and the store locator instance as second argument. If nothing is
  • provided all available data will be listed in a generic info window.
  • @property _options.infoWindow.additionalMoveToBottomInPixel - Additional
  • move to bottom relative to the marker if an info window has been opened.
  • @property _options.infoWindow.loadingContent - Content to show in the info
  • window during info window load.
  • @property _options.search - If a number is given a generic search will be
  • provided and given number will be interpret as search result precision
  • tolerance to identify a marker as search result.
  • @property _options.search.stylePropertiesToDeriveFromInputField - List of
  • cascading style properties to derive from input field and use for search
  • box.
  • @property _options.search.properties - Specify which store data should
  • contain given search text.
  • @property _options.search.maximumNumberOfResults - Limits the auto complete
  • result list.
  • @property _options.search.loadingContent - Markup to display while the
  • results are loading.
  • @property _options.search.generic - Specifies options for the additional
  • generic search to add to specific search results.
  • @property _options.search.generic.number - A tuple describing a range of
  • minimal to maximal limits of additional generic google suggestions depending
  • on number of local search results.
  • @property _options.search.generic.maximalDistanceInMeter - Range to specify
  • maximal distance from current position to search suggestions.
  • @property _options.search.generic.filter - Specifies a callback which gets a
  • relevant place to decide if the place should be included (returns a boolean
  • value).
  • @property _options.search.generic.prefer - Specifies a boolean value
  • indicating if generic search results should be the first results.
  • @property _options.search.generic.retrieveOptions - Specifies how a generic
  • place search should be done (google maps request object specification).
  • @property _options.search.content - Defines how to render the search
  • results. This can be a callback or a string returning or representing the
  • search results. If a function is given and a promise is returned the info
  • box will be filled with the given loading content and updated with the
  • resolved data. The function becomes search results as first argument, a
  • boolean value as second argument indicating if the maximum number of search
  • results was reached and the store locator instance itself as third argument.
  • If nothing is provided all available data will be listed in a generic info
  • window.
  • @property _options.search.resultAggregation - "Union" or "cut".
  • @property _options.search.normalizer - Pure function to normalize strings
  • before searching against them.
  • @property _options.onInfoWindowOpen - Triggers if a marker info window will
  • be opened.
  • @property _options.onInfoWindowOpened - Triggers if a marker info window has
  • finished opening.
  • @property _options.onAddSearchResults - Triggers before new search results
  • appears.
  • @property _options.onRemoveSearchResults - Triggers before old search
  • results will be removed.
  • @property _options.onOpenSearchResults - Triggers before search result box
  • appears.
  • @property _options.onCloseSearchResults - Triggers before search result box
  • will be hidden.
  • @property _options.onMarkerHighlighted - Triggers after a marker starts to
  • highlight.


npm i storelocator

DownloadsWeekly Downloads






Unpacked Size

138 kB

Total Files


Last publish


  • avatar