No code
Customize label text for a single label

This tutorial will walk you through how to use filters in the Mapbox Studio style editor to customize the label text for a single label.

Getting started

Before getting started, you will need to create a Mapbox account to use the Mapbox Studio style editor. You can create an account at

Create a new style

Log into your Mapbox account and navigate to your Styles page. This is where all your styles are listed. A style is a set of rules for how your map will be drawn on the page. It defines how all of your data should be styled and includes references to your data and map images (icons, markers, patterns), fonts. For more about styles, see the Styles section of the Mapbox Studio Manual.

To create a new style from your Styles page, click the New Style button, name your new style ‘Mapbox’, select the Basic template, and click the Create button. The style editor will automatically open with the Basic template style ready for editing.

Mapbox Studio new style dialog

Use the style editor

The Mapbox Studio style editor is a visual tool for creating custom map styles to your exact specifications. Take a look at the layers on the left side of the style editor screen. Each layer can be customized in a variety of ways including (but not limited to) changing labels.

Duplicate a layer and apply a filter

To customize label text for a single label, start by clicking + New layer. The editor will show your map in x-ray mode, which displays all of the data in your style’s sources, regardless of whether or not that data is visible in the styled version of your map.

Click the label that you would like to change. When a popup appears with information about that layer, click the Select button. This will add that tileset as your data Source. In the filter field, create a filter by clicking + Add filter. Choose the name field, choose the is any of condition, and type ‘United States’ into the Empty field. This will exclude everything except the label you want to override, in this case the United States label. Click the Create layer button.

Animation showing the layer creation process

Change text

After you’ve created your new layer, you won’t see any changes to your map. This is because the layer has not yet been styled. With your new layer still selected, type whatever you want in the Text field field for your new layer to change its label:

Mapbox studio layer text field dialog

You can even combine tokens, which let you pull text field values out of the data, with your own text. Change the input next to Text field to ‘{name} is a country’.

Result of changing layer text field dialog

Add other custom labels

You can use the same process to change other labels as well. Duplicate the layer again, then change the filter from ‘United States’ to ‘Canada’ to add a custom label for Canada. You can also select multiple layers at once by holding down command (Mac) or CTRL (Windows) while clicking to select layers to change style properties for multiple layers at once.

Mapbox studio custom layer text for Canada

Layers higher in your layer list will be shown with higher priority that layers lower in the list, so place your layers with customized labels higher in the list.

Final product

Congratulations! You’ve updated your map using filters to display custom labels for specific labels. To learn more about using the Mapbox Studio style editor, check out the Mapbox Studio Manual.

final product with customized labels