PMTiles for MapLibre GL ​

PMTiles is designed to be read directly in the browser by the MapLibre GL renderer, for either thematic overlay tilesets or basemap tilesets.

For a guide on integrating the Protomaps basemap tileset into MapLibre GL, see Basemaps for MapLibre.

Installation ​

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

npm install pmtiles

import { Protocol } from "pmtiles";

import { Protocol } from "pmtiles";

let protocol = new Protocol();
maplibregl.addProtocol("pmtiles",protocol.tile);

let protocol = new Protocol();
maplibregl.addProtocol("pmtiles",protocol.tile);

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

{
  "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");
    }
  }, []);

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.

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",
    }
  }
}

{
  "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"
    }
  }
}

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

Next Steps ​

• Integrating Basemap Styles into MapLibre