Mapbox Studio Classic style quickstart

Mapbox Studio Classic uses a language called CartoCSS to determine the look of a map. You can manipulate the map’s colors, sizes, and shapes by applying specific CartoCSS rules. Read the CartoCSS manual for a more detailed introduction to the language.

In this guide, we’ll take the Mapbox Basic style and add buildings, roads, and parks by writing CartoCSS. We’ll also make the map style interactive by adding tooltip to the POI (points of interest) layer.

Getting started

Before you start, you’ll need to download Mapbox Studio Classic.

Creating a style project

Create a new style by clicking on Styles & Sources in the lower left and click New style or source. Select the Basic style.

Create style

The basic project includes basic styling for for roads, city names, admin borders, rivers, and so on.

Inspecting the vector source

Center the map preview around New York City and increase the zoom level of the map to z17. Click the icon on the map preview pane. Although the map currently looks empty, there are many features available for styling in this area.

Mapbox Studio Classic includes a vector source inspector that will show you all layers and features for the vector source. Like the DOM inspector in web browsers, the vector source inspector shows you details about the fields and features in vector tiles that can be styled. Click a building polygon on the map to see its properties.


By inspecting the map, we found that buildings are stored on the building layer. We’ll use building as the selector to style the buildings with CartoCSS.

Toggle the icon again to return to the normal map preview.

Add a stylesheet tab

Let’s add a new CartoCSS tab to hold our new styles. Click on the + button on the top right of the style editor to add a new tab. Name your tab custom.


Styling buildings

Right now the map doesn’t show any buildings, because they aren’t styled. Let’s style the building to add them to the map. Add the following CartoCSS to your custom stylesheet and then click Save.

#building[zoom>=14] {
  polygon-fill: #eee;
  line-width: 0.5;
  line-color: #ddd;

The code above does the following:

  • #building selects the building layer as the one that will be styled.
  • [zoom>=14] restricts the styles to zoom level 14 or greater.
  • polygon-fill: #eee fills the building polygons with a light grey color.

Your buildings should look like this:

Styling buildings

To add depth to our buildings at higher zoom levels, let’s add another set of rules that use the building selector to render polygons as block-like shapes. Add the following CartoCSS to your custom stylesheet right after the code you added above. Click Save to save and see your changes.

#building[zoom>=16] {
  building-fill: #eee;
  building-fill-opacity: 0.9;
  building-height: 4;

Your buildings at higher zoom levels should now look like this:

Building symbolizer

Styling parks

Next, let’s adds parks to the map by styling them. Add the following CartoCSS to your custom stylesheet and then click Save.

#landuse[class='park'] {
  polygon-fill: #dec;

#poi_label[maki='park'][scalerank<=3][zoom>=15] {
  text-name: @name;
  text-face-name: @sans;
  text-size: 10;
  text-wrap-width: 60;
  text-fill: #686;
  text-halo-fill: #fff;
  text-halo-radius: 1;
  text-halo-rasterizer: fast;

The code above does the following:

  • #landuse selects features from the landuse layer.
  • [class='park'] restricts the landuse layer to features where the class attribute is park.
  • #poi_label selects the poi_label layer for labeling parks.
  • [maki='park'][scalerank<=3][zoom>=15] restricts the poi_label layer to prominent park labels and restricts their visibility to zoom level 15 or greater.
  • text-name: @name sets the field that label contents will use for their text. It references the existing @name variable defined in the style tab.
  • text-face-name: @sans sets the font to use for displaying labels. It references the existing @sans variable defined in the style tab.
  • text-wrap-width: 60 sets a maximum width for a single line of text.
  • text-halo-rasterizer: fast uses an alternative optimized algorithm for drawing halos around text that improves rendering speed.

Your parks should look like this:

Styling parks

Labeling roads

Finally, let’s adds road labels. Add the following CartoCSS to your custom stylesheet and then click Save.

#road_label[zoom>=13] {
  text-name: @name;
  text-face-name: @sans;
  text-size: 10;
  text-placement: line;
  text-avoid-edges: true;
  text-fill: #68a;
  text-halo-fill: #fff;
  text-halo-radius: 1;
  text-halo-rasterizer: fast;

The code above does the following:

  • #road_label selects features from the road_label layer.
  • [zoom>=13] restricts the road_label layer to zoom level 13 or greater.
  • text-placement: line sets labels to follow the orientation of lines rather than horizontally.
  • text-avoid-edges: true forces labels to be placed away from tile edges to avoid being clipped.

Your road labels should now look like this:

labeling roads

Adding custom fonts

Mapbox Studio Classic comes with a list of fonts to use out of the box. You can see the full list from the Fonts panel. You can also add a custom font - let’s try that with our style.

Download fonts Junction and Chunk from open-source type collective, League of Moveable Type. Next, open your style’s .tm2 folder and create a new fonts folder. Copy the .otf files from both fonts into the new folder.

new fonts folder

Note: .woff, .ttf, and .otf are all acceptable font formats in Mapbox Studio Classic, however only use one format to reduce file size of your map on upload.

Before you can use the font, you must set the font directory reference. In the style CartoCSS tab, search for the Map element and add font-directory: url("fonts/");. Click Save and your code should look like this:

Map {
  background-color: @land;
  font-directory: url("fonts/");

Open the Fonts tab and you will now see your custom fonts listed in Mapbox Studio Classic. You can use your fonts by name anywhere in your style and they will be packaged with the style when uploaded to Mapbox or exported as a .tm2z.

fonts tab updated

Change the font variables in the style CartoCSS tab from Source Sans Pro to ChunkFive Regular, Junction Light, and Junction Bold.

// Fonts
@sans: 'ChunkFive Regular';
@sans_italic: 'Junction Light';
@sans_bold: 'Junction Bold';

Save and admire your new font!

new map with custom fonts

Adding UTFGrid interactivity

Let’s add interactivity to the POI labels on the map. First, quit and close Mapbox Studio Classic. From your .tm2 folder, open the project.yml file in a text editor. Remove the single quotes (' ') to the right of interactivity_layer and replace like so:

interactivity_layer: poi_label

Now remove the single quotes (' ') to the right of template field and replace with the following HTML/Mustache template code:

template: |-
  <br /><small></small>
  <br /><small></small>
  <br /><small><a href=''>Website</a></small>

The code above is doing the following:

  • <strong>{{name}}</strong> adds the name of the POI in bold text.
  • {{#type}}<br /><small>{{type}}</small>{{/type}} adds the type of POI in small text if it exists.
  • {{#address}}<br /><small>{{address}}</small>{{/address}} adds the address of the POI in small text if it exists.
  • {{#website}}<br /><small><a href='{{website}}'>Website</a></small>{{/website}} adds the website of the POI in small text with a link to the website if it exists.

Restart Studio and hover over a park location to see your layer in action.

UTFGrid layer

Note: After making edits to the project.yml file in a text editor you should quit and restart Mapbox Studio Classic to see your changes. Mapbox Studio Classic loads up your project into memory and currently does not detect changes from other text editors.


To upload your project open the Settings panel and then click Upload to Mapbox.

Upload style

Mission complete

Your map style is now deployed Mapbox on your Styles page and has a map ID. You can use this map with any of the Mapbox developer APIs to integrate into your apps and sites.

Want to build more with Mapbox Studio Classic? Check out these guides:

Next article:

Mapbox Studio Classic source manual

Get the hang of working with data sources in Mapbox Studio Classic. We'll go over overzooming, buffers, layers, and more.

Additional questions? Ask our support team or learn more about How Mapbox Works.