Skip to content

Changing Specific Place Labels on the Map

Free

Starter

Standard

Professional

Have you found wanted to change the label of a particular feature on your map? Maybe you have to display a political viewpoint, or just want to add your own label to the map to make a place more prominent?

This tutorial will cover what you need to know, along with example code for MapLibre GL JS and MapLibre GL Leaflet.

Finding the label to change

The simplest approach to changing labels is to modify your map style. Normally the text-field is a simple property getter, like ["get", "name:en"]. We'll replace the simple getter with conditional logic based on the ID.

For example, if you want to rename the Gulf of Mexico, here's how you'd change your style:

  "text-field": [
-   ["get", "name:en"]
+   "case",
+   ["==", ["id"], 3056391900],
+   "Gulf of America",
+   ["get", "name:en"]
  ],

While the mechanism is extremely simple, it does rely on you knowing two things: the feature and layer ID. We've made it easy to get these with the map below. Just find the label you're looking for, click on it, and copy the ID and source layer.

© Stadia Maps © OpenMapTiles © OpenStreetMap

Changing the label

Now that we have a feature ID and a source layer, we can go about modifying our stylesheet. Here's how you can do it on the fly in JavaScript!

To change the layer in MapLibre GL JS, you'll need to add some code in a style load listener. For a full example of how to set up a full-page map, check our quickstart tutorial.

var map = new maplibregl.Map({
    container: 'map',
    style: 'https://tiles.stadiamaps.com/styles/alidade_smooth.json',  // Style URL; see our documentation for more options
    center: [-87, 24],  // Initial focus coordinate
    zoom: 4
});

map.on('style.load', (e) => {
    const style = map.getStyle();

    for (const targetLayer of style.layers) {
        // We're interested in layers that display items from water_name
        if (targetLayer["source-layer"] === 'water_name') {
            // Add some switching logic for the text-field, matching against the feature ID: 3056391900
            // If you have another feature you need update, you will need to make adjustments to the case condition below
            targetLayer.layout['text-field'] = [
                'case',
                ["==", ["id"], 3056391900],
                "Gulf of America",
                ["get", "name:en"]
            ];
        }
    }
    map.setStyle(style);
});

You can change labels in leaflet too, if you're using the MapLibre GL Leaflet plugin. For a full example of how to set up vector tiles in Leaflet, check our quickstart tutorial. To change the layer in MapLibre GL Leaflet, you'll need to add some code in a style load listener.

const lmap = L.map('map').setView([24, -87], 5);
const gl = 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(lmap);

const map = gl.getMaplibreMap();

map.on('style.load', (e) => {
    const style = map.getStyle();

    for (const targetLayer of style.layers) {
        // We're interested in layers that display items from water_name
        if (targetLayer["source-layer"] === 'water_name') {
            // Add some switching logic for the text-field, matching against the feature ID: 3056391900
            // If you have another feature you need update, you will need to make adjustments to the case condition below
            targetLayer.layout['text-field'] = [
                'case',
                ["==", ["id"], 3056391900],
                "Gulf of America",
                ["get", "name:en"]
            ];
        }
    }
    map.setStyle(style);
});

Updating the name from Gulf of Mexico to Gulf of America

Next Steps

And that's it. The above examples are extendable to more features by adding additional cases. If you're already hosting a custom style, you may rather edit the style directly, but this demonstrates the overall approach.

Once you're ready to move beyond localhost testing, 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