Custom Map Styling¶

Want to change the look and feel of the map? Custom styles allow you to change the color scheme of an existing style, change the language of place labels, and more.

Vector Maps¶

One major benefit to vector map tiles is that you can change the style to suit your liking (even dynamically!). Our vector tiles are compatible with the popular OpenMapTiles schema, and these base layers can be styled to fit a wide range of use cases.

MapLibre styles are the most common method of styling vector tiles. Other renderers such as OpenLayers and Tangram have their own styling tools as well, but we'll only cover GL JSON styles here as they are the most widely used. You can use these styles on the web via MapLibre GL JS, and on mobile via either MapLibre Native or Flutter MapLibre GL.

Modifying an Existing MapLibre Style¶

We recommend using Maputnik, an open-source style editor, to create and edit GL JSON styles. The easiest way to get started is by selecting "Open" from the Maputnik menu bar, entering the JSON URL for one of our house styles, and customizing it to your liking.

Maputnik has a bit of a learning curve, so editing an existing style is a great way to familiarize yourself with the tools before starting something from scratch.

Hosting or Bundling your Custom Style¶

Once you're happy with the result, you'll need to host the style somewhere: either on your web server or bundled with your app. Just point MapLibre at your custom style (URL or embedded JSON) instead of ours! If you or want to use your own sprites or fonts, read the next sections to learn about the extra steps involved. You will need to host these too along with your style JSON.

Advanced: Starting from Scratch or Porting from Another Vendor¶

If you're starting from another vendor, the first thing you'll need to know is what schema their vector tiles follow. For OpenMapTiles sources, then things should more or less "just work." For others, you will need to figure out how to map between their schema and the OpenMapTiles schema on your own. We also offer global elevation and other datasets via our additional data tilesets page, where you can find documentation and URLs.

Below you'll find a skeleton on which to build your own style, pre-filled with the URLs for our OpenMapTiles source, sprites (you can substitute alidade_smooth for any of our map styles), and glyphs (fonts). If you need custom sprites and glyphs, the following sections give an overview of what you'll need.

{
  "sources": {
    "openmaptiles": {
      "type": "vector",
      "url": "https://tiles.stadiamaps.com/data/openmaptiles.json",
      "attribution": "© Stadia Maps © OpenMapTiles © OpenStreetMap"
    }
  },
  "sprite": "https://tiles.stadiamaps.com/styles/alidade-smooth/sprite",
  "glyphs": "https://tiles.stadiamaps.com/fonts/{fontstack}/{range}.pbf",
  "layers": [...]
}

Advanced: Customizing Sprites¶

You can generate your own sprite files using Spreet, and host them on your web server. Then add them to your JSON style (using the sprite key).

Note that (as in the example JSON above) you should not include the suffix or extension in the URL. For example, if your output base name is sprite, you would use the following URL in the JSON style https://my-domain.com/path/to/sprite. Mapbox/MapLibre will then request https://my-domain.com/path/to/sprite.json and https://my-domain.com/path/to/sprite@2x.png respectively (@2x being appended automatically for retina/HiDPI displays).

Advanced: Customizing Fonts¶

In our own themes, we have rolled up our default font into a "super-font" stack with the fallback order we want. This makes themes easier to edit, and we've listed them in the Stadia font families section below.

If you want to change the fallback order or remove specific fonts, you can mix and match from the full list below (collapsed).

As with sprites, if you want to use your own set of fonts, you will need to host these yourself.

You can use a tool like our own open-source build_pbf_glyphs CLI utility or MapLibre FontMaker to generate the SDF font glyphs. You will then need to update glyphs key in your style JSON accordingly.

The text-font property in a MapLibre Style is a list which specifies fonts in fallback order. This is quite handy, but introduces some complexity. We'll cover both approaches briefly.

Combining Glyphs Upfront¶

The easiest option is to never specify more than a single font in any font list. Then you can host your font glyphs in a directory of static files (as generated by build_pbf_glyphs). You can still have fallback fonts without any extra complexity server-side by combining glyphs upfront into "super fonts."

For example, you can roll up Latin script bold font and a Japanese bold font into a single "bold" font. Let's call this "MyFont Bold." You just need to specify the fonts and a fallback order (much as you would in the MapLibre style JSON). You can then reference "MyFont Bold" in your style, and host the glyphs for MyFont Bold in a directory of static files. Refer to the build_pbf_glyphs README for usage instructions.

Combining Glyphs Dynamically¶

If you need to handle fallback fonts dynamically via a list in your style, your server will need to know how to handle Mapbox-style fontstack requests. These combine requests for multiple fonts into a long URL. Your server software needs to select the glyphs in given fallback order. We have open-sourced the Rust crate, pbf_font_tools, that we use ourselves (also as part of build_pbf_glyphs). If you're using Node.js, have a look at glyph-pbf-composite, which can be integrated into most server stacks.

Raster Maps¶

Most customers ask us about raster tiles because they are using Leaflet. If that describes you, we have good news! Most Leaflet use cases for custom styles can be addressed with the maplibre-gl-leaflet plugin, which lets you render vector tiles inside Leaflet. Check out our example repository to see Leaflet in action with a custom style.

If you are still sure that you need raster tiles or static maps for your custom style, contact us for a quote.

Further Reading¶

The MapLibre Style Specification is the final authority on MapLibre styling. Even if you primarily use Maputnik for editing styles visually, this is still useful to have as a reference.

Guides¶

• Changing the Map Label Language (guide)
• Mapster WP Maps Plugin for WordPress (step-by-step tutorial)