widgets geoSearch

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

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

const widget = instantsearch.widgets.geoSearch({ 
  container: string|HTMLElement, 
  googleReference: object, 
  initialZoom: [number], 
  initialPosition: [LatLng], 
  templates: [GeoSearchTemplates], 
  cssClasses: [GeoSearchCSSClasses], 
  mapOptions: [object], 
  builtInMarker: [BuiltInMarkerOptions], 
  customHTMLMarker: [CustomHTMLMarkerOptions], 
  enableRefine: [boolean], 
  enableClearMapRefinement: [boolean], 
  enableRefineControl: [boolean], 
  enableRefineOnMapMove: [boolean], 
  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.

• 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]

  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.

• enableRefine[boolean]
  Default value: true

  If true, the map is used to search - otherwise it’s for display purposes only.

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

• transformItems[function]

  Function to transform the items passed to the templates.

LatLng

• latnumber

  The latitude in degrees.

• lngnumber

  The longitude in degrees.

GeoSearchTemplates

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

  Template to use for the marker.

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

  Template for the reset button.

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

  Template for the toggle label.

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

  Template for the redo button.

GeoSearchCSSClasses

• root[string|Array<string>]

  The root div of the widget.

• map[string|Array<string>]

  The map container of the widget.

• control[string|Array<string>]

  The control element of the widget.

• label[string|Array<string>]

  The label of the control element.

• selectedLabel[string|Array<string>]

  The selected label of the control element.

• input[string|Array<string>]

  The input of the control element.

• redo[string|Array<string>]

  The redo search button.

• disabledRedo[string|Array<string>]

  The disabled redo search button.

• reset[string|Array<string>]

  The reset refinement button.

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

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