Skip to content

MapLibre GL

Installation

If you're reading tiles from a Protomaps CDN deployment, your tile source is just a normal source defined in a MapLibre GL style.

{
	"sources": {
		"protomaps": {
		    "type": "vector",
		    "tiles": ["https://mycdn.com/tileset/{z}/{x}/{y}.mvt"],
		    "minzoom": 0,
		    "maxzoom": 10

		}
	}
}

For reading PMTiles directly from cloud storage, you'll need the pmtiles JavaScript library.

The JavaScript library includes a plugin for MapLibre GL that uses its addProtocol feature.

npm install pmtiles
import * as pmtiles from "pmtiles";
let protocol = new pmtiles.Protocol();
maplibregl.addProtocol("pmtiles",protocol.tile);
{
	"sources": {
		"protomaps": {
		    "type": "vector",
		   	"url": "pmtiles://https://example.com/example.pmtiles",
		}
	}
}

Using the pmtiles:// protocol will automatically derive a minzoom and maxzoom for your Source.

React

addProtocol works best if it is only called once in the lifecycle of your application. A way to accomplish this in React is with a hook like this at the root component:

import maplibregl from 'maplibre-gl';
import { Protocol } from 'pmtiles';

...

useEffect(() => {
    let protocol = new Protocol();
    maplibregl.addProtocol("pmtiles",protocol.tile);
    return () => {
      maplibregl.removeProtocol("pmtiles");
    }
  }, []);

See this CodeSandbox example for a minimal working setup.

Vector Basemaps

Examples of JSON themes for MapLibre GL will appear in the basemaps repository.

The protomaps-themes-base NPM module contains basemap layer definitions compatible with OpenStreetMap downloads from Protomaps.

npm install protomaps-themes-base
import layers from 'protomaps-themes-base';
style: {
    version:8,
    glyphs:'https://cdn.protomaps.com/fonts/pbf/{fontstack}/{range}.pbf',
    sources: {
        "protomaps": {
            type: "vector",
            url: "...",
            attribution: '<a href="https://protomaps.com">Protomaps</a> © <a href="https://openstreetmap.org">OpenStreetMap</a>'
        }
    },
    layers: layers("protomaps","light")
}

the default export from protomaps-themes-base is a function that takes 2 arguments:

  • the source name of the basemap.

  • the theme, one of light, dark, white, black, grayscale or debug.

Raster or Terrain PMTiles

For raster tiles you'll just need to change the type of your source to raster:

{
	"sources": {
		"protomaps": {
		    "type": "raster",
		   	"url": "pmtiles://https://example.com/example.pmtiles",
		}
	}
}

Protomaps also distributes terrain tilesets in the Terrarium RGB encoding. These have a special source type in MapLibre GL:

{
	"sources": {
		"protomaps": {
		    "type": "raster-dem",
		   	"url": "pmtiles://https://example.com/example.pmtiles",
		   	"encoding": "terrarium"
		}
	}
}