Basemaps for MapLibre

Assets

To render a full basemap, you'll need not only a style and a tileset, but also MapLibre fontstack and spritesheet assets.

The assets referenced by the glyphs and sprite style properties can be downloaded as ZIP files at the basemaps-assets repository, if you need to host them yourself or offline.

Fonts

The glyphs key references a URL hosting pre-compiled fontstacks, required for displaying text labels in MapLibre. Fontstacks can be created with the font-maker tool.

glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf'

When a style layer defines a text-font like Noto Sans Regular, this will create requests for a URL like https://protomaps.github.io/basemaps-assets/fonts/Noto%20Sans%20Regular/0-255.pbf.

You can view a list of available fonts in the GitHub repository.

Sprites

The sprite key references a URL specific to one of the default themes:

sprite: "https://protomaps.github.io/basemaps-assets/sprites/v4/light"

These are required for townspots, highway shields and point of interest icons.

Loading styles as JSON

Because MapLibre styles are JSON documents, the simplest way to define a style in your application is with static JSON. You can use the Get style JSON feature of maps.protomaps.com to generate static JSON for a specific theme and style package version.

Creating styles programatically

For more control and less code, you can add use the protomaps-themes-base NPM package as a dependency.

Using the npm package

npm install protomaps-themes-base

import layers from 'protomaps-themes-base';

style: {
    version: 8,
    glyphs:'https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf',
    sprite: "https://protomaps.github.io/basemaps-assets/sprites/v4/light",
    sources: {
        "protomaps": {
            type: "vector",
            url: "pmtiles://https://example.com/example.pmtiles",
            //       ^-- Remember to prefix the URL with pmtiles://
            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, like protomaps in the sources example above.

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

Using a CDN

Loading the protomaps-themes-base package from NPM will define the protomaps_themes_base global variable.

<script src="https://unpkg.com/protomaps-themes-base@4/dist/protomaps-themes-base.js" crossorigin="anonymous"></script>

layers: protomaps_themes_base.default("protomaps","light")