connectors connectGeoSearch

Edit this page


The GeoSearch connector provides the logic to build a widget that will display the results on a map. It also provides a way to search for results based on their position. The connector provides functions to manage the search experience (search on map interaction or control the interaction for example).


Note that the GeoSearch connector uses the geosearch capabilities of Algolia. Your hits must have a _geoloc attribute in order to be passed to the rendering function.

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


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

const makeGeoSearch= instantsearch.connectors.connectGeoSearch(
function renderFn(
renderOpts: GeoSearchRenderingOptions,
isFirstRendering: boolean) {
// render the custom GeoSearch widget
} );

const customGeoSearch = makeGeoSearch(instanceOpts: CustomGeoSearchWidgetOptions);

Connector options


  • itemsArray<Object>

    The matched hits from Algolia API.

  • refine(Bounds) => undefined

    Sets a bounding box to filter the results from the given map bounds.

  • clearMapRefinement() => undefined

    Reset the current bounding box refinement.

  • isRefinedWithMap() => boolean

    Return true if the current refinement is set with the map bounds.

  • toggleRefineOnMapMove() => undefined

    Toggle the fact that the user is able to refine on map move.

  • isRefineOnMapMove() => boolean

    Return true if the user is able to refine on map move.

  • setMapMoveSinceLastRefine() => undefined

    Set the fact that the map has moved since the last refinement, should be call on each map move. The call to the function triggers a new rendering only when the value change.

  • hasMapMoveSinceLastRefine() => boolean

    Return true if the map has move since the last refinement.

  • widgetParamsObject

    All original CustomGeoSearchWidgetOptions forwarded to the renderFn.

  • position[LatLng]

    The current position of the search.


  • northEastLatLng

    The top right corner of the map view.

  • southWestLatLng

    The bottom left corner of the map view.


  • latnumber

    The latitude in degrees.

  • lngnumber

    The longitude in degrees.


  • 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. When the position option is provided this option will be ignored. 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[(Array<object>) => Array<object>]

    Function to transform the items passed to the templates.


// This example use Leaflet for the rendering, be sure to have the library correctly setup
// before trying the demo. You can find more details in their documentation (link below).
// We choose Leaflet for the example but you can use any libraries that you want.
// See:

let map = null;
let markers = [];

// custom `renderFn` to render the custom GeoSearch widget
function renderFn(GeoSearchRenderingOptions, isFirstRendering) {
  const { items, widgetParams } = GeoSearchRenderingOptions;

  if (isFirstRendering) {
    map =;

    L.tileLayer('https://{s}{z}/{x}/{y}.png', {
        '&copy; <a href="">OpenStreetMap</a> contributors',

  markers.forEach(marker => marker.remove());

  markers ={ _geoloc }) =>
    L.marker([, _geoloc.lng]).addTo(map)

  if (markers.length) {

// connect `renderFn` to GeoSearch logic
const customGeoSearch = instantsearch.connectors.connectGeoSearch(renderFn);

// mount widget on the page
    container: document.getElementById('custom-geo-search'),

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