Skip to content

Custom Map Styling

Vector Tiles

One major benefit to using 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. 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 GL Native or Flutter MapLibre GL.

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.

Tip

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. Hosting your own style JSON file is straightforward, but if you or want to use your own sprites, read on. This is a bit more complex and you'll need to host these yourself too. You will also need to modify the JSON style to point to your assets.

If your custom style will be accessing our tiles with an API key (for example, in a mobile app), you need to include your API key in the style. Specifically it will need to be added to any Stadia Maps sources, such as the openmaptiles.json URL under sources. Simply add the api_key as a query parameter like this: https://tiles.stadiamaps.com/data/openmaptiles.json?api_key=YOUR-API-KEY.

Customizing Sprites

You can generate your own sprite files using Spreet. This utility will generate a JSON and PNG, but you omit the suffix and extension in the JSON style. 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 for retina/HiDPI displays).

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.

Stadia font families

  • Stadia Regular
  • Stadia Italic
  • Stadia Bold
  • Stadia Semibold

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

Full individual font list
  • Noto Sans Arabic Light
  • Noto Sans Arabic Medium
  • Noto Sans Arabic Regular
  • Noto Sans Armenian Light
  • Noto Sans Armenian Medium
  • Noto Sans Armenian Regular
  • Noto Sans Ethiopic Light
  • Noto Sans Ethiopic Medium
  • Noto Sans Ethiopic Regular
  • Noto Sans Georgian Light
  • Noto Sans Georgian Medium
  • Noto Sans Georgian Regular
  • Noto Sans Hebrew Light
  • Noto Sans Hebrew Medium
  • Noto Sans Hebrew Regular
  • Noto Sans JP Light
  • Noto Sans JP Medium
  • Noto Sans JP Regular
  • Noto Sans Light
  • Noto Sans Medium
  • Noto Sans Regular
  • Noto Sans SC Light
  • Noto Sans SC Medium
  • Noto Sans SC Regular
  • Noto Sans TC Light
  • Noto Sans TC Medium
  • Noto Sans TC Regular
  • Noto Sans Thai Light
  • Noto Sans Thai Medium
  • Noto Sans Thai Regular
  • Open Sans Bold
  • Open Sans Italic
  • Open Sans Regular
  • Open Sans Semibold
  • SeoulNamsan B
  • SeoulNamsan L
  • SeoulNamsan M

If you want to use your own set of fonts, you will need to host these yourself.

Warning

Make sure that you are in compliance with any font licensing requirements before deploying maps with additional fonts.

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 in your style accordingly.

The text-font property is a list which specifies fonts in fallback order. The easiest approach is to ensure this list only ever has a single font (one entry). 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 using the combine feature to roll up fallback lists into "super fonts." This gives you a single font to reference in the style, and fewer files to host. Refer to the build_pbf_glyphs README for the latest usage instructions.

If you still want to handle fallback fonts via the standard list approach, your server will need to know how to handle Mapbox fontstack requests. These combine requests for multiple fonts with a preference into a long URL. Your server software needs to select the glyphs in preference order using techniques such as those shown in pbf_font_tools. If you're using Node.js, you can integrate a library like glyph-pbf-composite into your server.

Raster Tiles

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 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