---
title: "How to migrate/switch from MapLibre to MapTiler | JavaScript maps SDK"
description: "Steps to switch from MapLibre GL JS to MapTiler SDK."
---
> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.
# How to migrate/switch from MapLibre to MapTiler
This tutorial provides guidance on transitioning or changing from MapLibre to MapTiler. If you currently utilize MapLibre GL JS in your application, updating it to use the MapTiler SDK JS is a straightforward process.
In most cases, you can simply uninstall `maplibre-gl` and install `@maptiler/sdk` in your node packages or change the CDN links. Additionally, you will need to replace all instances of `maplibregl` with `maptilersdk` in your TypeScript, JavaScript, and HTML/CSS code. This ensures a seamless integration of the MapTiler SDK JS into your existing application.
Next, we will see the main changes that must be made to migrate your application from MapLibre to MapTiler.
## Installation
### NPM module setup
Uninstall `maplibre-gl` and install `@maptiler/sdk`
```bash
npm uninstall --save maplibre-gl
npm install --save @maptiler/sdk
```
### Basic JavaScript setup
Replace the JS and CSS import from CDN references.
##### MapLibre GL JS
```html
```
##### MapTiler SDK JS
```html
```
## Replace maplibregl with maptilersdk
Look in your application and replace `maplibregl` with `maptilersdk` in your TypeScript, JavaScript and HTML/CSS files. Some examples below
##### MapLibre GL JS
```js
const map = new maplibregl.Map({
....
const marker = new maplibregl.Marker()
....
```
##### MapTiler SDK JS
```js
const map = new maptilersdk.Map({
....
const marker = new maptilersdk.Marker()
....
```
## Replace the api key or accessToken
Find the variable where you store your actual [MapTiler API key](https://cloud.maptiler.com/account/keys/) in the code and replace it with `maptilersdk.config.apiKey`.
##### MapLibre GL JS
```js
const key = YOUR_MAPTILER_API_KEY_HERE;
```
##### MapTiler SDK JS
```js
maptilersdk.config.apiKey = YOUR_MAPTILER_API_KEY_HERE;
```
## Initialize the web map
##### MapLibre GL JS
With MapLibre GL JS, you initialize a new map like this:
```js
const map = new maplibregl.Map({
container: 'map', // container's id or the HTML element to render the map
style: `https://api.maptiler.com/maps/streets-v4/style.json?key=${key}`, // 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 own custom basemap styles by using the [customize tool](https://www.maptiler.com/cloud/customize/) style editor.
Checkout the list of [MapTiler SDK JS Map styles](https://docs.maptiler.com/sdk-js/api/map-styles/#mapstylelist)
##### MapLibre GL JS
You need to write the full URL of the style. If we make an update to a style (new version), you have to modify your codebase to have the latest version of styles. You must put the API key in every URL.
```js
`https://api.maptiler.com/maps/streets-v4/style.json?key=${key}` // style URL
```
##### MapTiler SDK JS
Always use the latest version of styles. No need to type along style URL. No more putting the API key in every URL.
```js
`maptilersdk.MapStyle.STREETS` // style URL
```
## Map controls
### Zoom and rotate controls
##### MapLibre 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 maplibregl.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
##### MapLibre GL JS
To display the `GeolocateControl`, you must add the control to the map.
```js
// Add geolocate control to the map.
map.addControl(
new maplibregl.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
##### MapLibre 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
maplibregl.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
##### MapLibre 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.
```js
// Use setLayoutProperty to set the value of a layout property in a style layer.
// The three arguments are the id of the layer, the name of the layout property,
// and the new property value.
map.setLayoutProperty('country-label', 'text-field', [
'get',
`name_${language}`
]);
map.setLayoutProperty('continent-label', 'text-field', [
'get',
`name_${language}`
]);
map.setLayoutProperty('state-label', 'text-field', [
'get',
`name_${language}`
]);
...
```
###### Change the default map language
To change the default map language (or initial map language), you have to go into the [MapTiler Map design tool](https://www.maptiler.com/cloud/customize/) and modify the map style. You have to do this for each style.
##### 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.
```js
//change the map language to French
map.setLanguage(maptilersdk.Language.FRENCH);
```
###### 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
##### MapLibre 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 use the `TerrainControl`.
```js
map.on('style.load', () => {
map.addSource('terrainSource', {
'type': 'raster-dem',
'url': `https://api.maptiler.com/tiles/terrain-rgb-v2/tiles.json?key=${key}`,
'tileSize': 512,
'maxzoom': 14
});
// add the DEM source as a terrain layer with exaggerated height
map.setTerrain({ 'source': 'terrainSource', 'exaggeration': 1.5 });
// add the TerrainControl
map.addControl(
new maplibregl.TerrainControl({
source: 'terrainSource',
exaggeration: 1
})
});
});
```
##### 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 or add the 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,
});
```
## MapTiler logo attribution
Free plan maps require the logo. It is required to place the MapTiler logo, with a link to https://maptiler.com/, on all maps in case you are not subscribed to any of the commercial plans of the Service. The MapTiler logo must be visible, readable and should appear in the left bottom corner of the map.
##### MapLibre GL JS
You **must have** something like this in your application to **comply** with the MapTiler **Terms and Conditions**.
```html
```
##### MapTiler SDK JS
The MapTiler logo attribution is **automatically added** to the map.
## Related examples
### [Switch from Mapbox](https://docs.maptiler.com/sdk-js/examples/switch-from-mapbox/)
Tutorials
Guide for migrating from Mapbox 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.
