---
title: "How to migrate/switch from Mapbox to MapTiler | JavaScript maps SDK"
description: "Guide for migrating from Mapbox GL JS to MapTiler SDK."
---

# 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

### NPM module setup

Uninstall `mapbox-gl` and install `@maptiler/sdk`

```bash
npm uninstall --save mapbox-gl
npm install --save @maptiler/sdk
```

### Basic JavaScript setup

Replace the JS and CSS import from CDN references.

##### Mapbox GL JS

```html
<script src='https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js'></script>
<link href='https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css' rel='stylesheet' />
```

##### MapTiler SDK JS

```html
<script src="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.umd.min.js"></script>
<link href="https://cdn.maptiler.com/maptiler-sdk-js/v4.2.0/maptiler-sdk.css" rel="stylesheet" />
```

## 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

```js
const map = new mapboxgl.Map({
  ....

const marker = new mapboxgl.Marker()
  ....
```

##### MapTiler SDK JS

```js
const map = new maptilersdk.Map({
  ....

const marker = new maptilersdk.Marker()
  ....
```

## 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](https://cloud.maptiler.com/account/keys/).

##### Mapbox GL JS

```js
mapboxgl.accessToken = YOUR_MAPBOX_API_KEY_HERE;
```

##### MapTiler SDK JS

```js
maptilersdk.config.apiKey = YOUR_MAPTILER_API_KEY_HERE;
```

## Initialize the web map

##### Mapbox GL JS

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

```js
const map = new mapboxgl.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68 // starting zoom
});
```

##### MapTiler SDK JS

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

```js
const map = new maptilersdk.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: maptilersdk.MapStyle.STREETS, // style URL
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68, // starting zoom
});
```

## Migrate the basemap styles

You can use the [MapTiler](https://www.maptiler.com/cloud/) service to provide the basemap for your application. There are different [Map styles](https://docs.maptiler.com/sdk-js/api/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](https://www.maptiler.com/cloud/customize/) style editor.

### Style equivalence

| **Mapbox** | **MapTiler** |
| --- | --- |
| `mapbox://styles/mapbox/streets-v12` | `maptilersdk.MapStyle.STREETS` |
| `mapbox://styles/mapbox/outdoors-v12` | `maptilersdk.MapStyle.OUTDOOR` |
| `mapbox://styles/mapbox/light-v11` | `maptilersdk.MapStyle.DATAVIZ.LIGHT` |
| `mapbox://styles/mapbox/dark-v11` | `maptilersdk.MapStyle.DATAVIZ.DARK` |
| `mapbox://styles/mapbox/satellite-v9` | `maptilersdk.MapStyle.SATELLITE` |
| `mapbox://styles/mapbox/satellite-streets-v12` | `maptilersdk.MapStyle.HYBRID` |

Checkout the list of [MapTiler SDK JS Map styles](https://docs.maptiler.com/sdk-js/api/map-styles/#mapstylelist)

## Map controls

### Zoom and rotate controls

##### Mapbox GL JS

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

```js
// Add zoom and rotation controls to the map.
map.addControl(new mapboxgl.NavigationControl());
```

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

```js
// Add geolocate control to the map.
map.addControl(
  new mapboxgl.GeolocateControl({
    positionOptions: {
      enableHighAccuracy: true
    }
  })
);
```

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

```js
mapboxgl.setRTLTextPlugin(
  'https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.3/mapbox-gl-rtl-text.js',
  null,
  true // Lazy load the 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 default map language

By default, Mapbox GL JS 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.

```js
//change the map language to German
const map = new mapboxgl.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: 'mapbox://styles/mapbox/streets-v12', // style URL
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68 // starting zoom
  language: "de"
});
```

##### MapTiler SDK JS

###### 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](https://docs.maptiler.com/sdk-js/api/languages/). If you want to define the initial language of the map, just set the language in the **map constructor options**.

```js
//change the map language to German
const map = new maptilersdk.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: maptilersdk.MapStyle.STREETS,
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68, // starting zoom
  language: maptilersdk.Language.GERMAN
});
```

## 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**.

```js
map.on('style.load', () => {
  map.addSource('mapbox-dem', {
    'type': 'raster-dem',
    'url': 'mapbox://mapbox.mapbox-terrain-dem-v1',
    'tileSize': 512,
    'maxzoom': 14
  });
  // add the DEM source as a terrain layer with exaggerated height
  map.setTerrain({ 'source': 'mapbox-dem', 'exaggeration': 1.5 });
});
```

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

```js
//add the 3D terrain and the terrainControl
const map = new maptilersdk.Map({
  container: 'map', // container's id or the HTML element to render the map
  style: maptilersdk.MapStyle.STREETS,
  center: [8.5419, 47.3799], // starting position [lng, lat]
  zoom: 10.68, // starting zoom
  terrain: true, 
  terrainControl: true,
});
```

## Geocoding control

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

##### Mapbox GL JS

```html
<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>
```

```js
// Add the control to the map.
map.addControl(
    new MapboxGeocoder({
        accessToken: mapboxgl.accessToken,
        mapboxgl: mapboxgl
    })
);
```

##### MapTiler SDK JS

Check out the [MapTiler Geocoding control](https://docs.maptiler.com/sdk-js/modules/geocoding/) documentation to see all the usage options such as React, Svelte, MapLibre, etc.

```html
<script src="https://cdn.maptiler.com/maptiler-geocoding-control/v3.1.0/maptilersdk.umd.js"></script>
<link href="https://cdn.maptiler.com/maptiler-geocoding-control/v3.1.0/style.css" rel="stylesheet">
```

```js
// Add the control to the map.
const gc = new maptilersdkMaptilerGeocoder.GeocodingControl();
map.addControl(gc);
```

## Geocoding API

##### Mapbox

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

###### Forward

get `https://api.mapbox.com/search/geocode/v6/forward?q={query}`

###### Reverse

get `https://api.mapbox.com/search/geocode/v6/reverse?longitude={longitude}&latitude={latitude}`

##### MapTiler

Check out the official [MapTiler Geocoding API](https://docs.maptiler.com/cloud/api/geocoding/) documentation to see all the options.

###### Forward

get `https://api.maptiler.com/geocoding/{query}.json`

###### Reverse

get `https://api.maptiler.com/geocoding/{longitude},{latitude}.json`

## Related examples

### [Switch from MapLibre](https://docs.maptiler.com/sdk-js/examples/switch-from-maplibre/)

Tutorials

Steps to switch from MapLibre GL JS to MapTiler SDK.

### [Weather layer switcher](https://docs.maptiler.com/sdk-js/examples/weather-layer-switcher/)

Examples

Switch weather layers and view detailed data under cursors.

### [Start with AR maps](https://docs.maptiler.com/sdk-js/examples/ar-control/)

Examples

Add an AR control button to map 3D viewports.

### [Learn the basics](https://docs.maptiler.com/sdk-js/examples/how-to-use/)

Tutorials

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