Vector maps in Leaflet JS

Vector maps are made of mathematical interpretations of geometric features such as points, curves or polygons. Vector tiles are rendered on the client’s side with a style, which is a small text file that defines how certain map elements look and how they are displayed. Read more about Vector tiles in this article What are vector tiles and why you should care?

Leaflet doesn’t support vector tiles by default. For basemaps, it is recommended to use it with traditional raster tiles. To display vector tiles it is necessary to use one of the available plugins.

To use MapTiler maps you need an API KEY. Your MapTiler API KEY is on your MapTiler Cloud account page or Get your FREE API key here.

Next we will explain two ways how to create a map in Leaflet using your MapTiler maps.

The first way (the one recommended for base maps) is using the mapbox-gl-leaflet plugin, which is responsible for interpreting the GL style definition and creating the map directly. In a second way, using the VectorGrid plugin we have to define the style for each layer; this gives us more control of what we want to show on the map. (recommended for data overlays)

Vector tiles mapbox-gl-leaflet (plugin)

Leaflet can also load and render the vector tiles directly - with the help of the mapbox-gl-leaflet plugin.

Note: this plugin is experimental and is not actively supported by Mapbox. For support, please open an issue in the mapbox-gl-leaflet repository.

Vector tiles VectorGrid (plugin)

Leaflet has also the ability to load and render the vector tiles directly - with the help of the VectorGrid plugin.

The plugin is not yet ready for drawing the basemaps with fonts etc but is very practical for other applications.

VectorGrid cannot handle vector tile GL styles (yet), therefore first you have to define the styling for all the data layers with the Leaflet specific styling code. Check VectorGrid’s documentation for more info about how to define the styling.

Check out the schemas of the different MapTiler datasets

Example of style definition:

var vectorStyles = {
  water: {	// Apply these options to the "water" layer...
    fill: true,
    weight: 1,
    fillColor: '#06cccc',
    color: '#06cccc',
    fillOpacity: 0.2,
    opacity: 0.4,
  transportation: {	// Apply these options to the "transportation" layer...
    weight: 0.5,
    color: '#f2b648',
    fillOpacity: 0.2,
    opacity: 0.4,

  // And so on, until every layer in has a style

  // aeroway:
  // boundary:
  // building:
  // housenumber:
  // landcover:
  // landuse:
  // park:
  // place:
  // poi:
  // transportation:
  // transportation_name:
  // water:
  // water_name:
  // waterway:

Once your style is ready, create an instance of L.VectorGrid.Protobuf like this:

const openmaptilesUrl = "{z}/{x}/{y}.pbf?key={key}";

const openMapTilesLayer = L.vectorGrid.protobuf(openMapTilesUrl, {
  vectorTileLayerStyles: vectorStyles,
  subdomains: '0123',
  attribution: '© OpenStreetMap contributors, © MapTiler',
  key: `${key}`

And add your layer to your Leaflet map:


Full code example


Use the mapbox-gl-leaflet plugin for basemaps and the VectorGrid plugin for data overlays.