Use maps interactively with JavaScript

If you want to build a rich web map application and embedding a map using an iframe is not sufficient, you can insert a map into your web using JavaScript.

After you log in to MapTiler Cloud administration, click on one of the available maps and you will see under the Use vector style and Raster tiles headers links to Examples of usage with different JavaScript libraries. Click on any of these links and it will automatically generate you the whole web page code you can directly use or modify according to your needs. For raster tiles, you can also switch on HiDPI tiles for use on retina displays.

In the Free and Vector plan, only vector tiles are available, the raster tiles are in the higher paid plans.

Vector tiles

Vector tiles is a modern technology for displaying a map on a web. It is available in all plans, including the Free. It gives end-users better experience zooming and panning because the map is dynamically changing instead of loading a completely new layer with raster tiles. Vector tiles are also smaller and save not only storage space, but also internet traffic. Thanks to the vector technology, it automatically supports any resolution, including HiDPI (retina) displays.

The downside is the higher hardware requirement on client-side because the final map is rendered in the browser. It also requires up-to-date browsers with WebGL support. Due to its novelty, the support in different JavaScript viewers is also limited. Therefore we recommend using Mapbox GL JS, which has in-built support for vector tiles. It is also possible to use OpenLayers or Leaflet with a plugin for vector tiles.

Automatically generated source code for Mapbox GL JS viewer

Automatically generated source code for Mapbox GL JS viewer

Raster tiles

Raster tiles is a traditional method of displaying a map on a web. Due to the higher requirements for rendering and data storage, it is available for paid customers with higher plans only.

For raster tiles, you can use OpenLayers or Leaflet JavaScript libraries. The choice depends on your requirements.


OpenLayers is a mature robust JavaScript library rich on features and very flexible on deployment. With OpenLayers, you can build complex web applications and connect them with other GIS systems. It is also well documented and the development is very active.

The downside is a size, which is more than 10 times bigger than Leaflet. It is hard for a start but powerful.


Leaflet is a fresh, but already stable JavaScript library for displaying a map on a web. The main advantage is a smaller size and simplicity, where you can create an eye-candy web application in a few steps.

While it can do most of the task of OpenLayers, it can lack some of the advanced functionality. However, a lot of functions can be added by third-party plugins.

Automatically generated source code for OpenLayers viewer

Automatically generated source code for OpenLayers viewer

Maps generated by MapTiler Desktop

If you have a map in MapTiler Desktop, you have two easy options of how to show it on the web using OpenLayers or Leaflet. Before you start with rendering, you need to select an output format.

MBTiles can be easily uploaded to MapTiler Cloud and served using OpenLayers or Leaflet with above instructions.

If you prefer self-hosting, select Folder option, upload it to your server and open in a browser. There is a simple viewer with a menu on the left: here you can select the Source code for your favorite viewer.

Was this article helpful?
2 out of 4 found this helpful