How to migrate/switch from Mapbox to MapTiler

This tutorial shows the process of how to migrate/switch from Mapbox to MapTiler. If you are using Mapbox GL JS in an existing application, it is a straightforward task to update it and incorporate the MapTiler SDK JS.

In the majority of cases, you can easily accomplish this by uninstalling the mapbox-gl package and installing the @maptiler/sdk package within your node packages. Additionally, you may need to modify the CDN links and replace instances of mapboxgl with maptilersdk throughout your TypeScript, JavaScript, and HTML/CSS code.

Next, we will see the main changes that must be made to migrate your application from Mapbox to Maptiler.

Installation

1. Replace the JS and CSS import from CDN references.

   Mapbox GL JS

   MapTiler SDK JS

2. Uninstall mapbox-gl and install @maptiler/sdk

Replace mapboxgl with maptilersdk

Look in your application and replace mapboxgl with maptilersdk in your TypeScript, JavaScript and HTML/CSS files. Some examples below

Mapbox GL JS

MapTiler SDK JS

Replace the api key or accessToken

Find mapboxgl.accessToken in the code and replace it with maptilersdk.config.apiKey. Replace your Mapbox accessToken with your actual MapTiler API key.

Mapbox GL JS

MapTiler SDK JS

Initialize the web map

Mapbox GL JS

With Mapbox GL JS, you initialize a new map like this:

MapTiler SDK JS

You can initialize a map in a similar way using the MapTiler SDK JS

Migrate the basemap styles

You can use the MapTiler Cloud service to provide the basemap for your application. There are different Map styles to choose from such as streets, satellite imagery, outdoor, dataviz, OpenStreetMap, etc. Each style offers a range of variants that contain the same level of information and has the same purpose but use different color schemes like dark, light, etc. You can also create and use your custom basemap styles by using the customize tool style editor.

Style equivalence

Checkout the list of MapTiler SDK JS Map styles

Map controls

Zoom and rotate controls

Mapbox GL JS

To display zoom and rotate controls, you must add the NavigationControl to the map.

MapTiler SDK JS

The zoom and rotate controls are displayed by default on the map. So there is no need to add the NavigationControl to the map.

Geolocate control

Mapbox GL JS

To display the GeolocateControl, you must add the control to the map.

MapTiler SDK JS

The geolocate control is displayed by default on the map. So there is no need to add the GeolocateControl to the map.

Support for right-to-left languages

Mapbox GL JS

To support right-to-left languages such as Arabic and Hebrew you need to add and use the mapbox-gl-rtl-text plugin.

MapTiler SDK JS

Right-to-left languages are supported by default so there is no need to add any plugins.

Change the map’s language

Mapbox GL JS

Change the map language dynamically

To change the map language dynamically you have to use the setLayoutProperty method for each of the text layers you have on the map and change the text-field property. This forces you to review the style, find the IDs of the text layers and execute the function for each layer. To avoid doing this you can use the mapbox-gl-language plugin.

Change the default map language

By default, will not set a language so that the language of Mapbox tiles will be determined by the vector tile source’s TileJSON. To change the default map language (or initial map language), you have to go into Mapbox Studio and modify the map style. You have to do this for each style.

If you want to force the initial language of the map you can do it in the map constructor.

MapTiler SDK JS

Change the map language dynamically

To change the map language dynamically just call the method setLanguage. There’s no need to add any plugins or search for all text layers and change the text-filed property. The SDK does all this automatically for you.

Change the default map language

The SDK detects the language of the browser and displays the map in that language. There is no need to modify the style or load any plugin. Check the documentation about languages. If you want to define the initial language of the map, just set the language in the map constructor options.

Add 3D terrain to a map

Mapbox GL JS

To add the 3D terrain to a map you have to first add a data source of type raster-dem and then call the map’s setTerrain function.

To activate and deactivate the terrain dynamically you have to create your own control or add some plugin.

MapTiler SDK JS

To add the 3D terrain to a map just set the terrain: true in the map constructor options. To activate and deactivate the terrain dynamically add the terrainControl: true in the map constructor options. There’s no need to add a data source, add some plugin or create your own terrain control.

Geocoding control

How to easily switch to MapTiler Geocoding from any other provider.

Mapbox GL JS

MapTiler SDK JS

Check out the MapTiler Geocoding control documentation to see all the usage options such as React, Svelte, MapLibre, etc.

Geocoding API

Mapbox

Check out the official Mapbox Geocoding API documentation to see all the options.

Forward

Reverse

MapTiler

Check out the official MapTiler Geocoding API documentation to see all the options.

Forward

Reverse

Related examples

Weather layer switcher

Example

Switch the display of the different weather layers in the MapTiler Cloud Weather data set and get the data information at the point under the cursor.

Learn the basics

Example

This tutorial shows how to create a map and display it on a web page using MapTiler Cloud.

Switch from MapLibre

Example

This tutorial shows how to migrate/switch from MapLibre to MapTiler.

Start with AR maps

Example

Getting started with AR maps: The Augmented reality (AR) control adds a button on your map to create a 3D model of the viewport, including 3D terrain and any layer you have put on top. Compatible with WebXR or Apple Quick Look.