Sorry, you need to enable JavaScript to visit this website.

SearchBox integration

Overview of the tutorial

This tutorial shows the basic use of the SearchBox plugin to display it in a web page.

To start using the latest version of the SearchBox plugin, you need the following:

  • The SearchBox plugin can be used in three ways.
    • NPM
    • With a CDN:<version>/SearchBox-web.js - Note: Include the latest version in the URL.
    • Download it from this page: Downloads.

        In this tutorial we are using a CDN as an example.

We recommend that you have npm and Node.js already installed on your computer to quickly spin up a HTTP server to display the page we will create.

There are two ways to include the SearchBox into your page.

  • Using the SearchBox as an independent element.
  • Using the SearchBox as a control in the map.

Using the SearchBox as an independent element

Now, let's create a basic HTML file to display the SearchBox plugin. For this example we created a file named index.html.

Next, copy the following script to your index.html file.

                <!DOCTYPE html>
                <html class='use-all-space'>
                    <meta http-equiv='X-UA-Compatible' content='IE=Edge' />
                    <meta charset='UTF-8'>
                    <meta name='viewport'
                    <link rel='stylesheet' type='text/css' href=''/>
                    <script src=""></script>
                    <script src=""></script>

                        var options = {
                            searchOptions: {
                                key: '<your-tomtom-API-key>',
                                language: 'en-GB',
                                limit: 5
                            autocompleteOptions: {
                                key: '<your-tomtom-API-key>',
                                language: 'en-GB'
                        var ttSearchBox = new tt.plugins.SearchBox(, options);
                        var searchBoxHTML = ttSearchBox.getSearchBoxHTML();

Let's go over the important lines

First, we import all the necessary assets. In this case there are SearchBox styles, the plugin, and the Services library.

        <link rel='stylesheet' type='text/css' href=''>
        <script src=""></script>
        <script src=""></script>
  • SearchBox styles - these provide the styles for SearchBox.
  • SearchBox plugin - this provides the search box and its functionality to your page.
  • Services library - This provides the necessary tools to integrate Tomtom services with your application.

Then we define the basic options configuration. See the following code example.

    var options = {
        searchOptions: {
            key: '<your-tomtom-API-key>',
            language: 'en-GB',
            limit: 5
        autocompleteOptions: {
            key: '<your-tomtom-API-key>',
            language: 'en-GB'
  • searchOptions - this is for the Fuzzy Search service. For a full list of options please refer to the Fuzzy Search service documentation.
  • autocompleteOptions - this is for the Autocomplete service. For a full list of options please refer to the Autocomplete service documentation.
    If you pass this option, the results list will be extended by the results returned by the Autocomplete service. They are used as filters for the fuzzy search.

Remember to replace the placeholders with your real data.

<your-tomtom-API-Key> Your TomTom API Key generated earlier.

For more details on how to use the configuration options, please refer to the documentation.

Then, we can create our new SearchBox instance

   var ttSearchBox = new tt.plugins.SearchBox(, options);

and append it to our application. In our example it's the body of the document.

    var searchBoxHTML = ttSearchBox.getSearchBoxHTML();

Using the SearchBox as a control in the map

The workflow of adding the SearchBox as a control is almost the same. You need to include a Map in your page and add there created instance of SearchBox with subscribed event handlers.

To check how to add the Map, please refer to the Display a vector map tutorial.

    var map ={
        key: '<your-tomtom-API-Key>',
        container: 'map',
        center: [15.4, 53.0],
        zoom: 3
    var ttSearchBox = new tt.plugins.SearchBox(, options);
    var searchMarkersManager = new SearchMarkersManager(map);
    ttSearchBox.on('tomtom.searchbox.resultsfound', handleResultsFound);
    ttSearchBox.on('tomtom.searchbox.resultselected', handleResultSelection);
    ttSearchBox.on('tomtom.searchbox.resultfocused', handleResultSelection);
    ttSearchBox.on('tomtom.searchbox.resultscleared', handleResultClearing);
    map.addControl(ttSearchBox, 'top-left');

SearchBox options was described above.

Remember to replace the placeholders with your real data.

<your-tomtom-API-Key> Your TomTom API Key generated earlier.

For more map configuration options please refer to the Map documentation.

Then we define event handlers.

        function handleResultsFound(event) {
    var results =;

    if (results.length === 0) {

function handleResultSelection(event) {
    var result =;
    if (result.type === 'category' || result.type === 'brand') {

function fitToViewport(markerData) {
    if (!markerData || markerData instanceof Array && !markerData.length) {
    var bounds = new tt.LngLatBounds();
    if (markerData instanceof Array) {
        markerData.forEach(function (marker) {
    } else {
    map.fitBounds(bounds, { padding: 100, linear: true });

function getBounds(data) {
    var btmRight;
    var topLeft;
    if (data.viewport) {
        btmRight = [data.viewport.btmRightPoint.lng,];
        topLeft = [data.viewport.topLeftPoint.lng,];
    return [btmRight, topLeft];

function handleResultClearing() {
  • handleResultsFound - executes when the search results are found. The event handler clears previously founded results and draws new. After that, it will try to fit drawn results on a vewport by executing fitToViewport method.
  • handleResultSelection - executes in two cases:

        - results were found and a user presses arrow up/down;
        - results were found and a user chooses one by clicking on it;

  • handleResultClearing - executes when a user clicks on "X" button of the SearchBox. As a result, all founded results will be cleared from the map.

After all these predefined steps we can create SearchMarkersManager, which will be responsible for manipulation with a marker.

In our example it has draw and clear methods

          function SearchMarkersManager(map, options) { = map;
    this._options = options || {};
    this._poiList = undefined;
    this.markers = {};

SearchMarkersManager.prototype.draw = function (poiList) {
    this._poiList = poiList;
    this._poiList.forEach(function (poi) {
        var markerId =;
        var poiOpts = {
            name: poi.poi ? : undefined,
            address: poi.address ? poi.address.freeformAddress : '',
            distance: poi.dist,
            classification: poi.poi ? poi.poi.classifications[0].code : undefined,
            position: poi.position,
            entryPoints: poi.entryPoints
        var marker = new SearchMarker(poiOpts, this._options);
        this.markers[markerId] = marker;
    }, this);

SearchMarkersManager.prototype.clear = function () {
    for (var markerId in this.markers) {
        var marker = this.markers[markerId];
    this.markers = {};
    this._lastClickedMarker = null;

and SearchMarker, which will be responsible for appearance of the marker and providing possibility add/remove it from the map

               function SearchMarker(poiData, options) {
    this.poiData = poiData;
    this.options = options || {};
    this.marker = new tt.Marker({
        element: this.createMarker(),
        anchor: 'bottom'
    var lon = this.poiData.position.lng || this.poiData.position.lon;

SearchMarker.prototype.addTo = function (map) {
    this._map = map;
    return this;

SearchMarker.prototype.createMarker = function () {
    var elem = document.createElement('div');
    elem.className = 'tt-icon-marker-black tt-search-marker';
    if (this.options.markerClassName) {
        elem.className += ' ' + this.options.markerClassName;
    var innerElem = document.createElement('div');
    innerElem.setAttribute('style', 'background: white; width: 10px; height: 10px; border-radius: 50%; border: 3px solid black;');

    return elem;

SearchMarker.prototype.remove = function () {
    this._map = null;

For more advanced example of using the described code above please refer to the code tab of Search with autocomplete example.

Handling events

The SearchBox emits 7 different events:

  • tomtom.searchbox.inputrestored - fired when the input is restored. This happens when the user uses the arrows to navigate through the suggestions list and navigates back to the input.
  • tomtom.searchbox.loadingstarted - fired when a request in the background is started.
  • tomtom.searchbox.loadingfinished - fired when a request in the background is finished.
  • tomtom.searchbox.resultfocused - fired when the result is focused.
  • tomtom.searchbox.resultscleared - fired when the search results are cleared.
  • tomtom.searchbox.resultselected - fired when the user selects an element on the results list.
  • tomtom.searchbox.resultsfound - fired when the search results are found.

If you want to subscribe for an event, use the following example code:

                ttSearchBox.on('tomtom.searchbox.resultsfound', function(data) {

Option updating

If you have initialized the SearchBox and you want to change it's options later, you can do the following:

                    minNumberOfCharacters: 5,
                    showSearchButton: false,
                    labels: {
                        placeholder: 'Query e.g. TomTom'

The query method triggers the search with updated options. This is necessary if you want to update results for the user with new options.


For more details on how to use the configuration options, please refer to the documentation.

Run a HTTP server

Using a terminal, navigate to the directory containing our example.

For example:

        ~$  cd searchbox-example/

Install a lightweight HTTP server (you might need to run this command with admin/root privileges).

        npm install -g http-server

Then just simply run the following command.


Note that npm comes bundled with Node.js, so please make sure you have it installed on your machine.

So now it is time to see the results!

Open a browser and type this URL in the address bar: http://localhost:8080/index.html. You should be able to see the SearchBox!



From this tutorial you learned:

  • How to prepare a basic HTML page to use the SearchBox.
  • How to show the SearchBox on your map.