Maps SDK for Web - L.SearchBox

Class L.SearchBox

This widget displays a search input control over the map capable of executing search requests and displaying the results in a dropdown under the input.

By default the widget collapses when is empty and loses focus.

This widget uses the fuzzy search implementation to execute search requests.

Constructor

L.SearchBox([options])

Parameters

Name	Description	Required	Type/Values	Default
options	Options to be passed to the searchBox control	No	Object	None
options.placeholder	The placeholder text to be displayed inside searchBox	No	String	"Search for place..."
options.id	Id of a searchBox's DOM element	No	String	None
options.collapsed	Flag if checkbox is collapsed on initialization	No	Boolean	false
options.collapsible	Flag if searchBox can be collapsed	No	Boolean	true
options.location	Display location button to search for current location	No	Boolean	false
options.icon	Determines icon of the searchBox	No	String	"icon-search"
options.disablePOIs	Determines whether search results should not contain POIs	No	Boolean	false
options.viewportBoundingBox	Enables or disables searching on a currently visible map area. If unset, search service will use current map center.	No	Boolean	false
options.withPrompt	Should widget show user prompts while typing, the call will be throttled according to the following settings: `minNumberCharsPrompt`, `throttleTimePrompt`, `idleTimeKeyPress`	No	Boolean	true
options.searchOnDragEnd	This option defines what the widget should do after the user finish dragging the map (and therefore changing the maps's viewport). There are five possible values: `"always"`: The widget will repeat the last search everytime the map's viewport changes. `"open"`: The last search will be repeated only if the list of results was being displayed when the map's dragging occurs. `"never"`: No action will be taken when the user change the map's viewport. `true`: Alias of `"always"`. `false`: Alias of `"never"`.	No	String \| Boolean	"always"
options.minNumberCharsPrompt	Sets the minimal required number of characters that are required to perform search	No	Number	3
options.throttleTimePrompt	Sets the minimal time between the following search service calls when user types text into the input	No	Number	1000
options.idleTimeKeyPress	Sets the time between following key press events to assume the user finished typing the query	No	Number	200
options.language	Language code, for example 'en-GB', 'en-US', 'de-DE'. Full list is available here.	No	String	None
options.view	Sets the geopolitical view used in the search service. Accepted values: 'AR', 'IL', 'MA', 'IN', 'PK' and 'Unified'. Full list is available here.	No	String	None
options.serviceOptions	Options to be passed to service. See search service options	No	Object	None
options.imperialDistance	Set this option if you want to use a specific unit measurement system for the new instance of the widget instead of use the default unit	No	Boolean	null

Example

 // SearchBox with location button and Polish language
var widget = new L.SearchBox({
     location: true,
     language: 'pl-PL',
     view: 'IN'
 });
widget.addTo(map);

// some time later...
widget.language('de-DE');
widget.view('IN');

Methods

addLocationIcon( )

Adds the location icon.

clearResults( )

Method used to clear all the previous search results from the widget.

clearResultsContainer( )

Method used to clear the DOM elements from the search results container.

This method just remove the DOM elements but leave the cache with the previous results inside the widget.

collapse( )

Method used to collapse search. Collapsing is possible only if search is empty.

expand( )

Method used to expand collapsed search.

getLocation( ): L.Location

Method used to get embedded location widget (if set and added).

Returns

L.Location

language([languageCode])

A setter for the 'language' option.

The whitelist can be found here.

Parameters

Name	Description	Required	Type/Values	Default
languageCode	Language code, for example 'en-GB', 'en-US', 'de-DE'. Full list is available here .	No	String	None

removeLocationIcon( )

Removes the location icon.

search(text)

Start a search using a query string. This method update the content of the input control and also handle the search request.

Parameters

Name	Description	Required	Type/Values	Default
text	String, Object or reverse geocoding object (with the `query` key) as a search query	Yes	Object \| String	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.search("Amsterdam");

var reversedGeocodeResponse = {query: "Amsterdam"}
widget.search(reversedGeocodeResponse);

setIcon(className)

Sets the icon by styling search box input.

Parameters

Name	Description	Required	Type/Values	Default
className	Name of the CSS class that sets `background-image` property for search box input	Yes	String \| Undefined	None

setResultData(resultData)

Method used to feed the searchBox instance with one search result element.

Parameters

Name	Description	Required	Type/Values	Default
resultData	Result data given from search service. Must contain address and/or POI information.	Yes	Object	None

Example

var widget = (new L.SearchBox()).addTo(map);
var resultData = {
  address: {freeformAddress: "Amsterdam"},
  poi: { name: "TomTom, Oosterdoksstraat, Amsterdam, The Netherlands" }
}
widget.setResultData(resultData);

view([geopolViewCode])

A setter for the 'view' option.

Use this setter to set a geopolitical view. When this parameter is used the search service will return values taking in consideration the Geopolitical view used.

Accepted values: 'AR', 'IL', 'MA', 'IN', 'PK' and 'Unified'

Parameters

Name	Description	Required	Type/Values	Default
geopolViewCode	Geopotical view code. Full list is available at here .	No	String	None

Events

All the class events are keys of the Events static member.

To learn more about how to listen events please refer to this documentation.

ClearButtonClicked

Event that is fired when user clicks the clear search box input button.

Properties

Name	Description	Type/Values	Default
type	Event's name	String	"clearButtonClicked"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.ClearButtonClicked, function() {
  console.log("User clicked the clear button");
});

LocationError

Event that is fired when obtaining user's current location fails.

Properties

Name	Description	Type/Values	Default
eventObject	All failure information	Object	None
type	Event's name	String	"locationError"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.LocationError, function(eventObject) {
  console.log(eventObject);
});

ResultClicked

Event that is fired when user selects the result from list or when current location is identified.

Properties

Name	Description	Type/Values	Default
data	Selected result object from search service response	Object	None
text	The human readable string representation of selected result	String	None
type	Event's name	String	"resultClicked"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.ResultClicked, function(eventObject) {
  console.log(eventObject.text);
  console.log(eventObject.data);
});

ResultCreated

This event appears when response from search service is being processed. For each result which is being rendered on the prompt list such event is fired.

Properties

Name	Description	Type/Values	Default
data	The result from search service response that is being processed	Object	None
type	Event's name	String	"resultCreated"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.ResultCreated, function(eventObject) {
  console.log(eventObject.data);
});

ResultsCleared

Event that is fired when prompt results list is being cleared.

Properties

Name	Description	Type/Values	Default
type	Event's name	String	"resultsCleared"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.LocationsCleared, function() {
  console.log("Results were cleared");
});

ResultsDrawn

Event that is fired when the response from search service is already processed and rendered in a form of list of possible results.

Properties

Name	Description	Type/Values	Default
data	Array of search service results. Each result has, among other parameters, its `type`, `address` and `position`.	Array	None
type	Event's name	String	"resultsDrawn"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.ResultsDrawn, function(eventObject) {
  console.log(eventObject.data);
});

ResultsFound

Event that is fired when the response from search service appears for both normal and prompt query.

Properties

Name	Description	Type/Values	Default
data	Array of search service results. Each result has, among other parameters, its `type`, `address` and `position`.	Array	None
type	Event's name	String	"resultsFound"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.ResultsFound, function(eventObject) {
  console.log(eventObject.data);
});

SearchInputChanged

Whenever the input within the search box is changed by the user this event is triggered.

Properties

Name	Description	Type/Values	Default
data	The current text entered by the user	Object	None
text	Same as data	String	None
type	Event's name	String	"searchInputChanged"
target	Event's target	Element	None

Example

var widget = new L.SearchBox();
widget.addTo(map);
widget.on(L.SearchBox.Events.SearchInputChanged, function(eventObject) {
  console.log(eventObject.text);
});