widgets geoSearch

Edit this page

Description

The GeoSearch widget displays the list of results from the search on a Google Maps. It also provides a way to search for results based on their position. The widget also provide some of the common GeoSearch patterns like search on map interaction.

Requirements

Note that the GeoSearch widget uses the geosearch capabilities of Algolia. Your hits must have a _geoloc attribute in order to be displayed on the map.

Currently, the feature is not compatible with multiple values in the _geoloc attribute.

You are also responsible for loading the Google Maps library, it’s not shipped with InstantSearch. You need to load the Google Maps library and pass a reference to the widget. You can find more information about how to install the library in the Google Maps documentation.

Don’t forget to explicitly set the height of the map container (default class .ais-geo-search--map), otherwise it won’t be shown (it’s a requirement of Google Maps).

Live example

You can find an example at the end of the page or a live example in our widget showcase.

Usage

Usage
const search = instantsearch( /* parameters */ );

const widget = instantsearch.widgets.geoSearch({ container: string|HTMLElement, googleReference: object, initialZoom: [number], initialPosition: [LatLng], paddingBoundingBox: [Padding], templates: [GeoSearchTemplates], cssClasses: [GeoSearchCSSClasses], mapOptions: [object], builtInMarker: [BuiltInMarkerOptions], customHTMLMarker: [CustomHTMLMarkerOptions|boolean], enableClearMapRefinement: [boolean], enableRefineControl: [boolean], enableRefineOnMapMove: [boolean], enableGeolocationWithIP: [boolean], position: [LatLng], radius: [number], precision: [number], transformItems: [function], }: GeoSearchWidgetOptions);
search.addWidget(widget);

Options

GeoSearchWidgetOptions

  • containerstring|HTMLElement

    CSS Selector or HTMLElement to insert the widget.

  • googleReferenceobject

    Reference to the global window.google object.
    See the documentation for more information.

  • initialZoom[number]
    Default value: 1

    By default the map will set the zoom accordingly to the markers displayed on it. When we refine it may happen that the results are empty. For those situations we need to provide a zoom to render the map.

  • initialPosition[LatLng]
    Default value: {lat:0,lng:0}

    By default the map will set the position accordingly to the markers displayed on it. When we refine it may happen that the results are empty. For those situations we need to provide a position to render the map. This option is ignored when the position is provided.

  • paddingBoundingBox[Padding]
    Default value: {top:0,right:0,bottom:0,left:0}

    Add an inner padding on the map when you refine.

  • templates[GeoSearchTemplates]

    Templates to use for the widget.

  • cssClasses[GeoSearchCSSClasses]

    CSS classes to add to the wrapping elements.

  • mapOptions[object]

    Option forwarded to the Google Maps constructor.
    See the documentation for more information.

  • builtInMarker[BuiltInMarkerOptions]

    Options for customize the built-in Google Maps marker. This option is ignored when the customHTMLMarker is provided.

  • customHTMLMarker[CustomHTMLMarkerOptions|boolean]
    Default value: false

    Options for customize the HTML marker. We provide an alternative to the built-in Google Maps marker in order to have a full control of the marker rendering. You can use plain HTML to build your marker.

  • enableClearMapRefinement[boolean]
    Default value: true

    If true, a button is displayed on the map when the refinement is coming from the map in order to remove it.

  • enableRefineControl[boolean]
    Default value: true

    If true, the user can toggle the option enableRefineOnMapMove directly from the map.

  • enableRefineOnMapMove[boolean]
    Default value: true

    If true, refine will be triggered as you move the map.

  • enableGeolocationWithIP[boolean]
    Default value: true

    If true, the IP will be use for the geolocation. If the position option is provided this option will be ignored, since we already refine the results around the given position. See the documentation for more information.

  • position[LatLng]

    Position that will be use to search around.
    See the documentation for more information.

  • radius[number]

    Maximum radius to search around the position (in meters).
    See the documentation for more information.

  • precision[number]

    Precision of geo search (in meters).
    See the documentation for more information.

  • transformItems[function]

    Function to transform the items passed to the templates.

LatLng

  • latnumber

    The latitude in degrees.

  • lngnumber

    The longitude in degrees.

Padding

  • topnumber

    The top padding in pixels.

  • rightnumber

    The right padding in pixels.

  • bottomnumber

    The bottom padding in pixels.

  • leftnumber

    The left padding in pixels.

GeoSearchTemplates

  • clear[string|(object) => string]

    Template for the clear button.

  • toggle[string|(object) => string]

    Template for the toggle label.

  • redo[string|(object) => string]

    Template for the redo button.

GeoSearchCSSClasses

  • root[string|Array<string>]

    CSS class to add to the root element.

  • map[string|Array<string>]

    CSS class to add to the map element.

  • controls[string|Array<string>]

    CSS class to add to the controls element.

  • clear[string|Array<string>]

    CSS class to add to the clear element.

  • control[string|Array<string>]

    CSS class to add to the control element.

  • toggleLabel[string|Array<string>]

    CSS class to add to the toggle label.

  • toggleLabelActive[string|Array<string>]

    CSS class to add to toggle label when it’s active.

  • toggleInput[string|Array<string>]

    CSS class to add to the toggle input.

  • redo[string|Array<string>]

    CSS class to add to the redo element.

BuiltInMarkerOptions

  • createOptions[(item) => ]

    Function used to create the options passed to the Google Maps marker.
    See the documentation for more information.

  • events[{eventType: (object) => undefined}]

    Object that takes an event type (ex: click, mouseover) as key and a listener as value. The listener is provided with an object that contains event, item, marker, map.

CustomHTMLMarkerOptions

  • templatestring|(item) => string

    Template to use for the marker.

  • createOptions[(item) => ]

    Function used to create the options passed to the HTMLMarker.

  • events[{eventType: (object) => undefined}]

    Object that takes an event type (ex: click, mouseover) as key and a listener as value. The listener is provided with an object that contains event, item, marker, map.

Widget

  • render[function]

    Called after each search response has been received

  • getConfiguration[function]

    Let the widget update the configuration of the search with new parameters

  • init[function]

    Called once before the first search

Example

search.addWidget(
  instantsearch.widgets.geoSearch({
    container: '#geo-search-container',
    googleReference: window.google,
  })
);

Can't find what you are looking for? Open an issue, we'll get back to you.