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

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

View demo

The geoSearch widget lets you search for results based on their position within a specified area (a bounding box). It also provides features such as “search on map interactions”.

The geoSearch widget doesn’t let you search around a central point or within polygons. If you want this, you need to build your own UI on top of the Algolia API.

Requirements

Your hit records must have a _geoloc attribute so they can be displayed on the map.
You must load the Google Maps library and pass a reference to the widget: the library doesn’t come with InstantSearch.js.
You must explicitly set the map container’s height. For example:

CSS

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

Examples

JavaScript

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

Options

container

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

geoSearch({
  // ...
  container: "#geo-search",
});

googleReference

object

required

The reference to the global window.google object.

JavaScript

geoSearch({
  // ...
  googleReference: window.google,
});

initialZoom

number

default:1

By default, the map sets the zoom level based on the displayed markers (results). However, after InstantSearch has applied a refinement, there may be no results. When this happens, a specific zoom level is required to render the map.

JavaScript

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

initialPosition

object

default:"{lat: 0, lng: 0}"

By default, the map sets the position based on the displayed markers (results). However, after InstantSearch has applied a refinement, there may be no results. When this happens, a specific position is required to render the map.

JavaScript

geoSearch({
  // ...
  initialPosition: {
    lat: 48.864716,
    lng: 2.349014,
  },
});

mapOptions

object

The options forwarded to the Google Maps constructor.

JavaScript

geoSearch({
  // ...
  mapOptions: {
    streetViewControl: true,
  },
});

builtInMarker

object

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 tied to the marker.
events: object. An object that takes event types (such as click and mouseover) as keys and listeners as values. The listener is called with an object that contains properties event, item, marker, and map.

JavaScript

geoSearch({
  // ...
  builtInMarker: {
    createOptions(item) {
      return {
        title: item.name,
      };
    },
    events: {
      click({ event, item, marker, map }) {
        console.log(item);
      },
    },
  },
});

customHTMLMarker

object

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

createOptions: function. A function to create the options passed to the HTMLMarker. The only 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 (such as click and mouseover) as keys and listeners as values. The listener is called with an object that contains properties event, item, marker, and map.

JavaScript

geoSearch({
  // ...
  customHTMLMarker: {
    createOptions(item) {
      return {
        anchor: {
          x: 0,
          y: 0,
        },
      };
    },
    events: {
      click({ event, item, marker, map }) {
        console.log(item);
      },
    },
  },
});

enableRefine

boolean

default:true

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

JavaScript

geoSearch({
  // ...
  enableRefine: false,
});

enableClearMapRefinement

boolean

default:true

If true, a button is displayed on the map to allow users to clear any refinements.

JavaScript

geoSearch({
  // ...
  enableClearMapRefinement: false,
});

enableRefineControl

boolean

default:true

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

JavaScript

geoSearch({
  // ...
  enableRefineControl: false,
});

enableRefineOnMapMove

boolean

default:true

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

JavaScript

geoSearch({
  // ...
  enableRefineOnMapMove: false,
});

templates

object

The templates to use for the widget.

JavaScript

geoSearch({
  // ...
  templates: {
    // ...
  },
});

cssClasses

object

default:"{}"

The CSS classes you can override:

root. The widget’s root element.
map. The map element.
control. The control element.
label. The label for the control element.
selectedLabel. The control element’s selected label.
input. The control element’s input.
redo. The “Redo search” button.
disabledRedo. The disabled “Redo search” button.
reset. The “Reset refinement” button.

JavaScript

geoSearch({
  // ...
  cssClasses: {
    root: "MyCustomGeoSearch",
    map: ["MyCustomGeoSearchMap", "MyCustomGeoSearchMap--subclass"],
  },
});

Templates

You can customize parts of a widget’s UI using the Templates API. Each template includes an html function, which you can use as a tagged template. This function safely renders templates as HTML strings and works directly in the browser—no build step required. For details, see Templating your UI.

The html function is available in InstantSearch.js version 4.46.0 or later.

HTMLMarker

string | function

The template to use for the marker.

geoSearch({
  // ...
  templates: {
    HTMLMarker(_, { html }) {
      return html`<p>Your custom HTML Marker</p>`;
    },
  },
});

reset

string | function

The template for the reset button.

geoSearch({
  // ...
  templates: {
    reset(_, { html }) {
      return html`<strong>Clear the map refinement</strong>`;
    },
  },
});

toggle

string | function

The template for the toggle label.

geoSearch({
  // ...
  templates: {
    toggle(_, { html }) {
      return html`<strong>Search as I move the map</strong>`;
    },
  },
});

redo

string | function

The template for the redo label.

geoSearch({
  // ...
  templates: {
    redo(_, { html }) {
      return html`<strong>Redo search here</strong>`;
    },
  },
});

HTML output

HTML

<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.

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

Then it’s a 3-step process:

JavaScript

// 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
  }),
]);

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).

JavaScript

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

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

  // Render the widget
};

Rendering options

The following rendering option example code snippets use Leaflet to render the map. If you prefer not to use Leaflet, you can use another library (such as Google Maps or Mapbox).

items

object[]

Hits that matched the search request.

JavaScript

let 
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

object

The current search position, when applicable.

JavaScript

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

object

The search’s bounding box:

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

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

(eventType, hit, eventName) => void

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

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

JavaScript

// 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

function

Resets the current bounding box refinement.

isRefinedWithMap

function

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

toggleRefineOnMapMove

function

Toggles whether users can refine on map move.

isRefineOnMapMove

function

Returns true if users can refine on map move.

setMapMoveSinceLastRefine

function

Indicates that the map has moved since the last refinement. This function should be called on each map move. It helps ensure the map is only re-rendered when it has moved.

hasMapMoveSinceLastRefine

function

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

All original widget options forwarded to the render function.

First, create your custom widgets using a rendering function. Then, instantiate them with parameters. There are two kinds of parameters you can pass:

Instance parameters. Predefined options that configure Algolia’s behavior.
Custom parameters. Parameters you define to make the widget reusable and adaptable.

Inside the renderFunction, both instance and custom parameters are accessible through connector.widgetParams.

JavaScript

const customGeoSearch = connectGeoSearch(renderGeoSearch);

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

Instance options

enableRefineOnMapMove

boolean

default:true

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

JavaScript

customGeoSearch({
  enableRefineOnMapMove: false,
});

transformItems

function

default:"items => items"

A function that receives the list of items before they are displayed. It should return a new array with the same structure. Use this to transform, filter, or reorder the items.The function also has access to the full results data, including all standard response parameters and parameters from the helper, such as disjunctiveFacetsRefinements.

JavaScript

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

<div id="geo-search"></div>

InstantSearch.js

Import

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

InstantSearch.js

​Import

​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

Import

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