UI libraries / InstantSearch.js / Widgets

Dec. 04, 2023

geoSearch

Signature

geoSearch({
  container: string|HTMLElement,
  googleReference: object,
  // Optional parameters
  initialZoom: number,
  initialPosition: object,
  mapOptions: object,
  builtInMarker: object,
  customHTMLMarker: object,
  enableRefine: boolean,
  enableClearMapRefinement: boolean,
  enableRefineControl: boolean,
  enableRefineOnMapMove: boolean,
  templates: object,
  cssClasses: object,
});

Import

Copy

1
import { geoSearch } from 'instantsearch.js/es/widgets';

See code examples

See live example

About this widget

The geoSearch widget displays search results on a Google Map. It lets you search for results based on their position and provides some common usage patterns such as “search on map interactions”.

Requirements

The widget uses the geo search capabilities of Algolia. Your hits must have a _geoloc attribute so they can be displayed on the map.

The feature is currently incompatible with several values in the _geoloc attribute.

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

Make sure that you explicitly set the height of the map container (see below), otherwise it won’t show.

Copy
.ais-GeoSearch-map {
  height: 500px; /* You can change this height */
}

Examples

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

Options

Parameter Description


            container

type: string|HTMLElement

Required

The CSS Selector or HTMLElement to insert the widget into.

Copy

1
2
3
4
geoSearch({
  // ...
  container: '#geo-search',
});


            googleReference

type: object

Required

The reference to the global window.google object.

See the Google Maps documentation for more information.

Copy

1
2
3
4
geoSearch({
  // ...
  googleReference: window.google,
});


            initialZoom

type: number

default: 1

Optional

By default, the map sets the zoom based on to the markers that are displayed on it. Yet when InstantSearch.js refines the results, they may be empty. When it happens, it needs a zoom level to render the map.

Copy

1
2
3
4
geoSearch({
  // ...
  initialZoom: 4,
});


            initialPosition

type: object

default: { lat: 0, lng: 0 }

Optional

By default, the map sets the position based on to the markers that are displayed on it. Yet when InstantSearch.js refines the results, they may be empty. When it happens, it needs a position to render the map.

Copy

1
2
3
4
5
6
7
geoSearch({
  // ...
  initialPosition: {
    lat: 48.864716,
    lng: 2.349014,
  },
});


            mapOptions

type: object

Optional

The options forwarded to the Google Maps constructor.

See the Google Maps documentation for more information.

Copy

1
2
3
4
5
6
geoSearch({
  // ...
  mapOptions: {
    streetViewControl: true,
  },
});


            builtInMarker

type: object

Optional

The options for customizing the built-in Google Maps markers. This is ignored when the customHTMLMarker is provided. The object accepts multiple attributes:

createOptions: function: a function to create the options passed to the Google Maps marker. The function is called with item, which is the hit that is tied to the marker. You can find more information about the option in the Google Maps documentation.
events: object: an object that takes event types (e.g., click, mouseover) as keys and listeners as values. The listener is called with an object that contains properties event, item, marker and map.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
geoSearch({
  // ...
  builtInMarker: {
    createOptions(item) {
      return {
        title: item.name,
      };
    },
    events: {
      click({ event, item, marker, map }) {
        console.log(item);
      },
    },
  },
});


            customHTMLMarker

type: object

Optional

The options for customizing the HTML marker. InstantSearch.js provides an alternative to the built-in Google Maps markers to give a full control over the marker rendering. You can use plain HTML to build your marker (see templates.HTMLMarker). The object accepts several attributes:

createOptions: function: a function to create the options passed to the HTMLMarker. The only currently supported option is anchor. It lets you shift the marker position from the center of the element.
events: object: an object that takes event types (e.g., click, mouseover) as keys and listeners as values. The listener is called with an object that contains properties event, item, marker and map.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
geoSearch({
  // ...
  customHTMLMarker: {
    createOptions(item) {
      return {
        anchor: {
          x: 0,
          y: 0,
        },
      };
    },
    events: {
      click({ event, item, marker, map }) {
        console.log(item);
      },
    },
  },
});


            enableRefine

type: boolean

default: true

Optional

If true, the map is used for refining the search. Otherwise, it’s only for display purposes.

Copy

1
2
3
4
geoSearch({
  // ...
  enableRefine: false,
});


            enableClearMapRefinement

type: boolean

default: true

Optional

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

Copy

1
2
3
4
geoSearch({
  // ...
  enableClearMapRefinement: false,
});


            enableRefineControl

type: boolean

default: true

Optional

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

Copy

1
2
3
4
geoSearch({
  // ...
  enableRefineControl: false,
});


            enableRefineOnMapMove

type: boolean

default: true

Optional

If true, refine is triggered as you move the map.

Copy

1
2
3
4
geoSearch({
  // ...
  enableRefineOnMapMove: false,
});


            templates

type: object

Optional

The templates to use for the widget.

Copy

1
2
3
4
5
6
geoSearch({
  // ...
  templates: {
    // ...
  },
});


            cssClasses

type: object

default: {}

Optional

The CSS classes you can override:

root: the root element of the widget.
map: the map element.
control: the control element.
label: the label of the control element.
selectedLabel: the selected label of the control element.
input: the input of the control element.
redo: the “Redo search” button.
disabledRedo: the disabled “Redo search” button.
reset: the “Reset refinement” button.

Copy

1
2
3
4
5
6
7
8
9
10
geoSearch({
  // ...
  cssClasses: {
    root: 'MyCustomGeoSearch',
    map: [
      'MyCustomGeoSearchMap',
      'MyCustomGeoSearchMap--subclass',
    ],
  },
});

Templates

You can customize parts of the widget’s UI using the Templates API.

Every template provides an html function you can use as a tagged template. Using html lets you safely provide templates as an HTML string. It works directly in the browser without a build step. See Templating your UI for more information.

The html function is available starting from v4.46.0.

Parameter Description


            HTMLMarker

type: string|function

Optional

The template to use for the marker.

Copy

1
2
3
4
5
6
7
8
geoSearch({
  // ...
  templates: {
    HTMLMarker(_, { html }) {
      return html`<p>Your custom HTML Marker</p>`;
    },
  },
});

1
2
3
4
5
6
7
// String-based templates are deprecated, use functions instead.
geoSearch({
  // ...
  templates: {
    HTMLMarker: '<p>Your custom HTML Marker</p>',
  },
});


            reset

type: string|function

Optional

The template for the reset button.

Copy

1
2
3
4
5
6
7
8
geoSearch({
  // ...
  templates: {
    reset(_, { html }) {
      return html`<strong>Clear the map refinement</strong>`;
    },
  },
});


            toggle

type: string|function

Optional

The template for the toggle label.

Copy

1
2
3
4
5
6
7
8
geoSearch({
  // ...
  templates: {
    toggle(_, { html }) {
      return html`<strong>Search as I move the map</strong>`;
    },
  },
});


            redo

type: string|function

Optional

The template for the redo label.

Copy

1
2
3
4
5
6
7
8
geoSearch({
  // ...
  templates: {
    redo(_, { html }) {
      return html`<strong>Redo search here</strong>`;
    },
  },
});

HTML output

Copy
<div class="ais-GeoSearch">
  <div class="ais-GeoSearch-map">
    <!-- Map element here -->
  </div>
  <div class="ais-GeoSearch-control">
    <label class="ais-GeoSearch-label">
      <input class="ais-GeoSearch-input" type="checkbox">
      Search as I move the map
    </label>
  </div>
  <button class="ais-GeoSearch-reset">
    Clear the map refinement
  </button>
</div>

Customize the UI with connectGeoSearch

If you want to create your own UI of the geoSearch widget, you can use connectors.

To use connectGeoSearch, you can import it with the declaration relevant to how you installed InstantSearch.js.

Copy

1
import { connectGeoSearch } from 'instantsearch.js/es/connectors';

Then it’s a 3-step process:

// 1. Create a render function
const renderGeoSearch = (renderOptions, isFirstRender) => {
  // Rendering logic
};

// 2. Create the custom widget
const customGeoSearch = connectGeoSearch(
  renderGeoSearch
);

// 3. Instantiate
search.addWidgets([
  customGeoSearch({
    // instance params
  })
]);

See code examples

Create a render function

This rendering function is called before the first search (init lifecycle step) and each time results come back from Algolia (render lifecycle step).

const renderGeoSearch = (renderOptions, isFirstRender) => {
  const {
    object[] items,
    object position,
    object currentRefinement,
    function refine,
    function sendEvent,
    function clearMapRefinement,
    function isRefinedWithMap,
    function toggleRefineOnMapMove,
    function isRefineOnMapMove,
    function setMapMoveSinceLastRefine,
    function hasMapMoveSinceLastRefine,
    object widgetParams,
  } = renderOptions;

  if (isFirstRender) {
    // Do some initial rendering and bind events
  }

  // Render the widget
}

Rendering options

The examples built with the connector use Leaflet to render the map. Make sure to have the library correctly setup before trying the demo. You can find more details in the Leaflet documentation. We picked Leaflet but you can use any library you prefer (e.g., Google Maps, Mapbox, etc.)

Parameter Description


            items

type: object[]

The hits that matched the search request.

Copy
OpenStreetMap contributors',
    }).addTo(map);
  }

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

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

  if (markers.length) {
    map.fitBounds(L.featureGroup(markers).getBounds());
  }
};
" class="snippet-body ">
let map = null;
let markers = [];

const renderGeoSearch = (renderOptions, isFirstRender) => {
  const { items } = renderOptions;

  if (isFirstRender) {
    map = L.map(document.querySelector('#geo-search'));

    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      attribution:
        '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors',
    }).addTo(map);
  }

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

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

  if (markers.length) {
    map.fitBounds(L.featureGroup(markers).getBounds());
  }
};


            position

type: object

The current position of the search, when applicable.

Copy
OpenStreetMap contributors',
    }).addTo(map);
  }

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

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

  if (markers.length) {
    map.fitBounds(L.featureGroup(markers).getBounds());
  } else {
    map.setView(
      position || {
        lat: 48.864716,
        lng: 2.349014,
      },
      12
    );
  }
};
" class="snippet-body ">
let map = null;
let markers = [];

const renderGeoSearch = (renderOptions, isFirstRender) => {
  const { items, position } = renderOptions;

  if (isFirstRender) {
    map = L.map(document.querySelector('#geo-search'));

    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      attribution:
        '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors',
    }).addTo(map);
  }

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

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

  if (markers.length) {
    map.fitBounds(L.featureGroup(markers).getBounds());
  } else {
    map.setView(
      position || {
        lat: 48.864716,
        lng: 2.349014,
      },
      12
    );
  }
};


            currentRefinement

type: object

The current bounding box of the search, with:

northEast: { lat: number, lng: number }: the top right corner of the map view.
southWest: { lat: number, lng: number }: the bottom left corner of the map view.


            refine

type: function

Sets a bounding box to filter the results from the given map bounds. The function accepts an object with:

northEast: { lat: number, lng: number }: the top right corner of the map view.
southWest: { lat: number, lng: number }: the bottom left corner of the map view.


            sendEvent

type: (eventType, hit, eventName) => void

The function to send click or conversion events. The view event is automatically sent when this connector renders hits. You can learn more about the insights middleware.

eventType: 'click' | 'conversion'
hit: Hit | Hit[]
eventName: string

Copy
// For example,
sendEvent('click', hit, 'Location Starred');
// or
sendEvent('conversion', hit, 'Restaurant Saved');

/*
  A payload like the following will be sent to the `insights` middleware.
  {
    eventType: 'click',
    insightsMethod: 'clickedObjectIDsAfterSearch',
    payload: {
      eventName: 'Product Added',
      index: '<index-name>',
      objectIDs: ['<object-id>'],
      positions: [<position>],
      queryID: '<query-id>',
    },
    widgetType: 'ais.geoSearch',
  }
*/


            clearMapRefinement

type: function

Resets the current bounding box refinement.


            isRefinedWithMap

type: function

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


            toggleRefineOnMapMove

type: function

Toggles whether the user is able to refine on map move.


            isRefineOnMapMove

type: function

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


            setMapMoveSinceLastRefine

type: function

Sets whether the map has moved since the last refinement. This should be call on each map move. The call to the function triggers a new render only when the value changes.


            hasMapMoveSinceLastRefine

type: function

Returns true if the map has moved since the last refinement.


            widgetParams

type: object

All original widget options forwarded to the render function.

We first create custom widgets from our rendering function, then we instantiate them. When doing that, there are two types of parameters you can give:

Instance parameters: they are predefined parameters that you can use to configure the behavior of Algolia.
Your own parameters: to make the custom widget generic.

Both instance and custom parameters are available in connector.widgetParams, inside the renderFunction.

const customGeoSearch = connectGeoSearch(
  renderGeoSearch
);

search.addWidgets([
  customGeoSearch({
    // Optional parameters
    enableRefineOnMapMove: boolean,
    transformItems: function,
  })
]);

Instance options

Parameter Description


            enableRefineOnMapMove

type: boolean

default: true

Optional

If true, refine is triggered as you move the map.

Copy

1
2
3
customGeoSearch({
  enableRefineOnMapMove: false,
});


            transformItems

type: function

default: items => items

Optional

Receives the items and is called before displaying them. Should return a new array with the same shape as the original array. Useful for transforming, removing, or reordering items.

In addition, the full results data is available, which includes all regular response parameters, as well as parameters from the helper (for example disjunctiveFacetsRefinements).

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
customGeoSearch({
  transformItems(items) {
    return items.map(item => ({
      ...item,
      name: item.name.toUpperCase(),
    }));
  },
});

/* or, combined with results */
customGeoSearch({
  transformItems(items, { results }) {
    return items.query.length === 0
      ? items
      : items.map(item => ({
          ...item,
          name: `${item.name} (matching "${results.query}")`,
        }));
  },
});

Full example

Copy

OpenStreetMap contributors', }).addTo(map); map.on('moveend', () => { if (isUserInteraction) { const ne = map.getBounds().getNorthEast(); const sw = map.getBounds().getSouthWest(); refine({ northEast: { lat: ne.lat, lng: ne.lng }, southWest: { lat: sw.lat, lng: sw.lng }, }); } }); button.addEventListener('click', () => { clearMapRefinement(); }); container.appendChild(element); container.appendChild(button); } container.querySelector('button').hidden = !currentRefinement; markers.forEach(marker => marker.remove()); markers = items.map(({ _geoloc }) => L.marker([_geoloc.lat, _geoloc.lng]).addTo(map) ); isUserInteraction = false; if (!currentRefinement && markers.length) { map.fitBounds(L.featureGroup(markers).getBounds(), { animate: false, }); } else if (!currentRefinement) { map.setView(initialPosition, initialZoom, { animate: false, }); } isUserInteraction = true; }; // Create the custom widget const customGeoSearch = connectGeoSearch( renderGeoSearch ); // Instantiate the custom widget search.addWidgets([ customGeoSearch({ container: document.querySelector('#geo-search'), initialZoom: 12, initialPosition: { lat: 48.864716, lng: 2.349014, }, }) ]);" class="snippet-body ">

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
// Create the render function
let map = null;
let markers = [];
let isUserInteraction = true;

const renderGeoSearch = (renderOptions, isFirstRendering) => {
  const {
    items,
    currentRefinement,
    refine,
    clearMapRefinement,
    widgetParams,
  } = renderOptions;

  const {
    initialZoom,
    initialPosition,
    container,
  } = widgetParams;

  if (isFirstRendering) {
    const element = document.createElement('div');
    element.style.height = '100%';

    const button = document.createElement('button');
    button.textContent = 'Clear the map refinement';

    map = L.map(element);

    L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
      attribution:
        '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors',
    }).addTo(map);

    map.on('moveend', () => {
      if (isUserInteraction) {
        const ne = map.getBounds().getNorthEast();
        const sw = map.getBounds().getSouthWest();

        refine({
          northEast: { lat: ne.lat, lng: ne.lng },
          southWest: { lat: sw.lat, lng: sw.lng },
        });
      }
    });

    button.addEventListener('click', () => {
      clearMapRefinement();
    });

    container.appendChild(element);
    container.appendChild(button);
  }

  container.querySelector('button').hidden = !currentRefinement;

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

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

  isUserInteraction = false;
  if (!currentRefinement && markers.length) {
    map.fitBounds(L.featureGroup(markers).getBounds(), {
      animate: false,
    });
  } else if (!currentRefinement) {
    map.setView(initialPosition, initialZoom, {
      animate: false,
    });
  }
  isUserInteraction = true;
};

// Create the custom widget
const customGeoSearch = connectGeoSearch(
  renderGeoSearch
);

// Instantiate the custom widget
search.addWidgets([
  customGeoSearch({
    container: document.querySelector('#geo-search'),
    initialZoom: 12,
    initialPosition: {
      lat: 48.864716,
      lng: 2.349014,
    },
  })
]);

Did you find this page helpful?

geoSearch

About this widget

Requirements

Examples

Options

Templates

HTML output

Customize the UI with connectGeoSearch

Create a render function

Rendering options

Create and instantiate the custom widget

Instance options

Full example

On this page