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';

const { geoSearch } = instantsearch.widgets;
// or directly use instantsearch.widgets.geoSearch()

See this widget in action

Preview this widget and its behavior.

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

string | HTMLElement

required

The CSS Selector or HTMLElement to insert the widget into.

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

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

object

required

The reference to the global window.google object.

JavaScript

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

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

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

object

The options forwarded to the Google Maps constructor.

JavaScript

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

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

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

boolean

default:true

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

JavaScript

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

boolean

default:true

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

JavaScript

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

boolean

default:true

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

JavaScript

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

boolean

default:true

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

JavaScript

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

object

The templates to use for the widget.

JavaScript

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

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.

string | function

The template to use for the marker.

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

// String-based templates are deprecated, use functions instead.
geoSearch({
  // ...
  templates: {
    HTMLMarker: "<p>Your custom HTML Marker</p>",
  },
});

string | function

The template for the reset button.

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

// String-based templates are deprecated, use functions instead.
geoSearch({
  // ...
  templates: {
    reset: "Clear the map refinement",
  },
});

string | function

The template for the toggle label.

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

// String-based templates are deprecated, use functions instead.
geoSearch({
  // ...
  templates: {
    toggle: "Search as I move the map",
  },
});

string | function

The template for the redo label.

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

// String-based templates are deprecated, use functions instead.
geoSearch({
  // ...
  templates: {
    redo: "Redo search here",
  },
});

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';

const { connectGeoSearch } = instantsearch.connectors;
// or directly use instantsearch.connectors.connectGeoSearch()

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

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());
  }
};

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

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.

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.

(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',
  }
*/

function

Resets the current bounding box refinement.

function

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

function

Toggles whether users can refine on map move.

function

Returns true if users can refine on map move.

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.

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

boolean

default:true

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

JavaScript

customGeoSearch({
  enableRefineOnMapMove: false,
});

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>

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

InstantSearch.js

Import

See this widget in action

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

See this widget in action

​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