Switching from Raster to Vector Map Tiles¶

If you've ever zoomed in and out of a map quickly, you probably noticed little blank squares that filled in like a mosaic. This is a map tile. Most interactive electronic maps are constructed from tiles, which are then stitched together to form a complete interactive map.

Map tiles for interactive maps come in two main flavors: raster and vector. Raster tiles have been around for decades, but are gradually being replaced by a vector tiles, a newer format which has unique advantages for most applications.

Whether you're a seasoned developer looking to improve your maps or planning your first maps integration from scratch, this guide is for you. Let's get started!

Background¶

What are raster tiles?¶

As we mentioned in the intro, map tiles can be broadly classified as either raster or vector. Raster tiles are the simplest to understand, as they are just PNG or JPG images that get stitched together in a grid, so we'll start here.

Advantages¶

Raster tiles have been around for a long time, and even today, they have a number of unique advantages.

• Simplicity - Just about every device can render a PNG or JPG image, and it's very easy to build a performant renderer around these. Additionally, raster tiles don't require any other resources (such as fonts or icons) or special logic to render.
• Specificity - Map tiles simplify a lot of data into a form that's useful for the user. If you are working with a minimalist map style (like our Alidade Smooth family), raster tiles can be more bandwidth efficient, as they only contain the raw visible pixels.

Limitations¶

While raster tiles are battle tested and supported pretty much everywhere, they also have some inherent limitations.

• Inflexibility - You cannot change much about raster tiles. If you want to hide a certain layer, change the language of labels, or do just about anything else to alter the appearance of the tiles, you're out of luck.
• Scalability - Raster map tiles cannot be scaled up and down, meaning you need to send 4x as many pixels over the network for your maps to look good on modern "high DPI" displays. This problem also shows up when zooming in to a raster map as the tiles become blurry until the new ones are loaded.

What are vector tiles?¶

Vector tiles are a newer development, and are broadly viewed as the future of digital interactive maps. Rather than pixels, vector tiles contain a mathematical description of the geometry as well as structured data about each feature on the map.

Advantages¶

• Flexibility - Vector tiles aren't just raw pixels; the actual data is preserved in the tile. This means that you can seamlessly change the language of text labels, change the color scheme to suit your brand, or even switch styles dynamically based on the time of day or the user's device preferences. You can even completely change the camera angle for a 3D perspective.
• Scalability - Since vector shapes are expressed in mathematical terms, they can be scaled up and down smoothly. For example, when the user zooms in, they'll get a smooth scale-in without any pixelation. This is especially relevant on mobile devices, where users are used to continuous zoom for most applications rather than discrete steps.
• Cost - Many vendors, including Stadia Maps, charge per tile request. Switching to vector tiles can mean significant savings, as vector tiles cover a larger area. On average, we see users switching to vector making approximately 60% fewer tile requests.

Limitations¶

• Complexity - While vector tiles provide a lot of flexibility, this comes at the cost of complexity. Tiles need to be rendered client-side, and this may create performance concerns for older or embedded applications. Additionally, since vector maps require additional resources to be present, the initial map load typically involves a greater number of network requests.
• Size - For applications only requiring a low level of detail that don't utilize any of the 3D perspective features of vector tiles, the vector tiles can weigh a bit more. However, this is somewhat offset since all zooming past level 14 can use the information in the z14 tile.

Recap: Which should I use?¶

We've covered a lot of ground. To summarize, vector tiles offer greater flexibility, look great on any screen, and typically reduce costs by around 60%. However, if your application is targeting older devices or doesn't need a high level of detail (for example, our Alidade Smooth and Alidade Smooth Dark styles), raster tiles are not necessarily a bad option.

Now, let's dive into some practical tips on switching to vector tiles.

How can I switch to vector tiles?¶

Switching is easy. The first step is to select a style from our gallery (you can also build your own). You'll want to copy the vector style URL. Let's dive into using vector styles with the most popular frameworks!

Switching to MapLibre¶

MapLibre provides the greatest flexibility and feature support when it comes to vector tile rendering. If you want the best looking maps, a 3D camera, or dynamic styling, MapLibre is the way to go.

Web¶

We have an in-depth tutorial that covers the basics. For most use cases, the transition is easy: just swap out Leaflet or a similar renderer for MapLibre GL JS and use the code snippets or URLs of one of our styles. In addition to the tutorial, which covers creating a basic map and adding markers, we've compiled some resources below which cover the most common questions we receive:

• Marker clustering - When you have a map with a lot of markers, you typically want to cluster them into groups. This is not quite as intuitive as in some other frameworks (particularly Leaflet). We have a tutorial to get you started.
• Adding overlays - MapLibre GL JS supports a wide variety of overlays. We have tutorials covering drawing polylines (ex: a route) and polygons.

Mobile¶

We have quickstart tutorials to get you going on native iOS and Android, Flutter, and React Native. You can find all of these in our Native & Multi-platform maps overview.

Using vector tiles with Leaflet¶

If you're already using Leaflet and would prefer not to switch, you can add vector rendering support with the maplibre-gl-leaflet plugin. There are a few quirks, but if your needs are simple, there is often no need to rewrite your application.

Vanilla HTML and JavaScript¶

You can add the plugin by adding a few lines to the <head> section of your page or via npm install --save @maplibre/maplibre-gl-leaflet maplibre-gl.

<!-- MapLibre GL JS (handles the rendering) -->
<script type="text/javascript" src="//unpkg.com/maplibre-gl@4.0.2/dist/maplibre-gl.js"></script>
<link href="//unpkg.com/maplibre-gl@4.0.2/dist/maplibre-gl.css" rel="stylesheet" />

<!-- MapLibre GL Leaflet -->
<script src="https://unpkg.com/@maplibre/maplibre-gl-leaflet@0.0.20/leaflet-maplibre-gl.js"></script>

All you need to do to switch to vector is create your tile layer using L.maplibreGL instead of L.tileLayer. Here is an example using Alidade Smooth; you can substitute it with your preferred style.

- L.tileLayer('https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png', {
-     maxZoom: 20,
+ L.maplibreGL({
+     style: 'https://tiles.stadiamaps.com/styles/alidade_smooth.json',
      attribution: '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>, &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>',
  }).addTo(map);

If you'd like to see a complete vector integration example with a line-by-line walkthrough and a JSFiddle playground, check out our tutorial on vector tiles with Leaflet.

React Leaflet¶

If you're using React Leaflet, you can switch by adding a simple component and using that for your map tile layer. Our in-depth tutorial will show you exactly what to do.

Using vector tiles with OpenLayers¶

Some more advanced web mapping use cases require the power of OpenLayers. You can add support for OpenLayers using the ol-mapbox-style plugin. This is not supported quite as well as Leaflet yet, but it is a great option if you need the power of OpenLayers and want to switch to vector tiles.

First, you will need to load the plugin. You can either add this line to your HTML <head> section or npm install --save ol-mapbox-style@9.4.0.

<script src="https://unpkg.com/ol-mapbox-style@9.4.0/dist/olms.js"></script>

Then, you can use olms.apply, passing either the ID of the HTML element to use, or an existing OpenLayers map instance.

olms.apply('map', 'https://tiles.stadiamaps.com/styles/alidade_smooth_dark.json').then(function(map) {
    // Callback to configure the map if necessary
});

Wrapping up¶

We've covered the differences between raster and vector tiles, and when each is most appropriate. For the majority of applications, which benefit from vector tiles, we've gone over the most popular frameworks, highlighted the major gotchas, and linked to in-depth tutorials where available.

If we missed something that's got you stumped, reach out to us via email or our social media channels (you can find them in the footer).

Once you're ready to go live with your vector map, sign up for a free Stadia Maps account, and we'll walk through the next steps to registering your domain or getting an API key.

Get Started With a Free Account