Get started with CartoCSS

This guide is an introduction to styling a map with CartoCSS in Mapbox Studio Classic. You’ll learn the basics of CartoCSS by customizing the Mapbox Streets Classic style. You can follow the entire guide or jump around to different sections if you’re just looking for fast instruction.

Mapbox Studio Classic

Start by getting acquainted with Mapbox Studio Classic. If you haven’t already:

Starter styles

Mapbox Studio Classic ships with 16 starter styles for you to use or customize for your final map design. Starter styles make styling your maps faster and easier and can help you learn CartoCSS. To use them, launch Mapbox Studio Classic and click the Styles & Sources link on the bottom left (below your account photo). In this panel, you can choose a starter style to serve as the base for your own map designs. For more information on these styles, see the Getting Started with Mapbox Studio Classic guide.

Mapbox Studio Classic starter styles

These starter styles are powered by one of Mapbox’s curated vector tilesets, Mapbox Streets, which is a set of curated data from OpenStreetMap. If you’d like to use your own custom vector data to power your map style, choose a Blank source when creating a new project. Read more about that in our Getting Started with Mapbox Studio Classic guide.

Customize a starter style

In this guide, you will be customizing the Mapbox Streets Classic style. From Styles & Sources, click the Streets Classic style.

Save style

Start by naming your new style. From the Settings panel, change the default project name to “My Custom Streets Style”. Click Save as on the top left to save your style.

When you save a style, the project is saved as a .tm2 folder on your local drive. Make it a habit to save with each change - the map preview will reload with changes upon saving your Project. You can also refresh the map using Ctrl+R on your keyboard (Command+R for Mac).

Test style with Places

As you start designing styles or updating existing ones, use the Places feature located above the map to jump to different locations in the world.

This feature changes the preview of the single view map to a grid of different locations. It’s particularly helpful as you’re choosing fonts and colors to make sure your design works for different locations.

Save your own Places

In addition to the preset locations, you can save your own places by clicking the heart icon above the map to the right.

Basic CartoCSS

Mapbox Studio Classic uses a language called CartoCSS to style maps - it’s like CSS for map design.

CSS is a stylesheet language used to modify the appearance of HTML elements on a web page. In CSS, selectors are patterns used to select the elements you wish to style and assign properties and values to those elements.

CSS syntax looks like this:

selector {
  property: value;
}

With CartoCSS, the map’s individual data layers are the selectors. CartoCSS syntax looks like this:

#layer {
  property: value;
}

Mapbox source data come with a variety of layers. Following the example below, you can find the #water layer in Mapbox Studio Classic’s Layers panel and use CartoCSS to assign a fill color for the water – in this case a particular shade of blue, #73B6E6.

Layer CartoCSS Result
```scss #water { polygon-fill: #73B6E6; } ```

You can also style subsets of a layer based on a feature’s attributes, an example of which appears later in this guide.

Properties and values

For each type of data (point, line, polygon, or raster), there are different CartoCSS properties you can apply. You can find all properties and values from the Docs panel in Mapbox Studio Classic. Click on a property to read about how it works and values you can use.

As you begin to type a property into CartoCSS, hit tab on your keyboard to auto-complete that property name – this is a great way to get comfortable with CartoCSS! The tab works for both properties and values.

Code errors

We all make mistakes. Fortunately, Mapbox Studio Classic helps you with code errors by indicating the line of the first error and what may be the problem. You can click the orange highlighted line in the code panel for more specifics. In the example below, Mapbox Studio Classic indicates an error because a string value was passed when a float numeric value was expected.

Zoom levels

Control your map style zoom by zoom. Most data that looks great at a certain zoom level will need to be adjusted at higher or lower zoom levels.

With many data layers, displaying all features at every zoom level can be difficult to read. For instance, if you zoom into New York City, building number labels are hidden until you’ve zoomed to a specific building. Without a zoom level, house number labels would cover the map.

Instead, you can style house number labels to only be displayed at a specific zoom level.

You will find that zoom levels are added to almost all layers by default – it’s an important technique to keep your map layers and features organized.

Attributes

Like zoom levels, attributes help style specific layers and features on a map. A layer’s features may have many attributes or none at all. For example, the landuse layer has a class attribute and it’s values are cemetery, hospital, industrial, park, parking, pitch, sand, school, and wood. This means that the landuse layer can style all of those areas, but styling #landuse without specifying a class means all those areas would look the same. This means schools and cemeteries would share the same appearance - not a good look.

Instead, you can target each area with the layer’s class attribute. You can find the attributes for landuse by going to the Layers panel and clicking on the #landuse layer. (This works for any layer you’re wanting to style.)

If you want to style all the parks, you will add the attribute name (class) and value (park) to the layer selector. All the styles between the curly brackets will only apply to the parks:

#landuse[class='park'] {
  /* ... */
}

You can also nest the attributes to avoid repeating the layer name and add a zoom level:

#landuse[zoom>=7] {
  [class='pitch'] {
    polygon-fill: #fff; // all pitches will be white when zoom level is >= 7
  }
  [class='park'],
  [class='school'] {
    polygon-fill: #f00; // all parks and schools will be red when zoom level is >= 7
  }
  [class='cemetery'] {
    polygon-fill: #000; // all cemeteries will be black when zoom level is >= 7
  }
}

Variables

A variable in CartoCSS looks like this: @water. A variable is a way of saving information to use over and over again. A variable always starts with an @. Before you can use a variable, you must assign it a value.

A common example is water; typically, you want to use the same color for water no matter where it appears on your map.

@water: #73b6e6;

Now that the variable is set, you can use @water as a value for any color property.

#water {
  polygon-fill: @water;
}

You can create a variable for any CartoCSS value; not just colors. For example, you can assign a variable for font names, line widths, or languages. The name of the variable is up to you, but it’s a good idea to be as specific as possible. While @blue is specific, it’s use is not as clear as if you named the variable @water.

You don’t have to use variables when styling, but they help keep values that you use more than once consistent and organized. They also make it easier to update your map in the future. For example, in Streets Classic, the @water variable is used seven times. If the style didn’t use variables, the color hex code #73B6E6 would appear seven times throughout the CartoCSS tabs. If you wanted to change the color, you would have to manually find each of the seven instances and change them. With a variable, you can update the color in just one place.

Carto tabs

Write and edit your CartoCSS in the style panel on the right side of the Mapbox Studio Classic interface. Notice the tabs at the top of this section? Each tab contains different CartoCSS rules, but they all get applied to the same map. Tabs help you organize similar styles together. For example, the designer of Streets Classic grouped all the road styles in the roads tab and all the label styles in the labels tab.

Add a new CartoCSS tab by clicking the on the right of the tabs.

Tabs make it easier for others to browse your code and for you to make quick edits, but it’s fine to write your styles in a single CartoCSS tab.

Map design

Now it’s time to design your map with CartoCSS. Follow along in the following section to adjust this starter style and make it your own.

Color variables

Let’s give Streets Classic a new color scheme based on a simple color palette:

#ecf0f1
#95a5a6
#34495e
#f1c40f

For this section, you will work entirely in the vars CartoCSS tab. Scroll down to where it says LANDUSE & LANDCOVER COLORS.

  1. Change the land color to a very light blue: @land: #ecf0f1;
  2. Click save to see your changes.
  3. Click Places to see different views of your style.
  4. Change the water color to a darker blue: @water: #34495e;.
  5. Change the grass color to a steely gray: @grass: #95a5a6; (Use Places > Parks view).
  6. Click save to see your changes.

For the remaining color variables, you will reuse a couple variables. Here’s the complete code, but feel free to try your own colors:

@land:              #ecf0f1;
@water:             #34495e;
@grass:             #95a5a6;
@sand:              #7f8c8d;
@rock:              #d8d7d5;
@park:              @grass;
@cemetery:          @grass;
@wooded:            @grass;
@industrial:        #dddcdc;
@agriculture:       @land;
@snow:              @land;

@building:          darken(@land, 8);
@hospital:          @land;
@school:            @land;
@pitch:             @grass;
@sports:            @park;

@parking:           fadeout(@road_fill, 75%);

Finally, highlight the railways by making them yellow. Railways are located in the road colors. Go ahead and change them to this color: @rail_line: #f1c40f;.

The resulting map:

Font variables

For this style, all the font families are assigned as variables in the vars tab. Each variable represents a different font weight and style. The style uses Open Sans with a fallback font of Arial.

Try a different font family:

  1. Click Fonts from Mapbox Studio Classic’s toolbar.
  2. Scroll down until you find “Mark Offc Pro” and click on it to see its weights and styles.
  3. Replace each font variable value with the new font name.
  4. Click Save to see your styles changes.

Your font variables should look something like this:

@sans_lt:           "Mark Offc Pro Regular","Arial Unicode MS Regular";
@sans_lt_italic:    "Mark Offc Pro Italic","Arial Unicode MS Regular";
@sans:              "Mark Offc Pro Medium","Arial Unicode MS Regular";
@sans_bold:         "Mark Offc Pro Bold","Arial Unicode MS Regular";
@sans_italic:       "Mark Offc Pro Bold Italic","Arial Unicode MS Regular";
@sans_bold_italic:  "Mark Offc Pro Heavy Italic","Arial Unicode MS Regular";

Here’s the map with the new font:

Try experimenting with values by using different weights and styles. You can even add a completely different font family to make your labels a little more interesting.

Want to use a font that doesn’t come with Mapbox Studio Classic? You can also add custom fonts to your project.

Label language

The text-name property sets the language of the labels on the map. You can either specify a language for the labels, or you can have the labels be localized to a particular area. This is what it looks like when you have English labels:

#country_label {
  text-name: '[name_en]';
}

For most Mapbox styles, our designers saved the language of the labels as a @name variable. This means that if you’re customizing a Mapbox style, you only need to update the value of the @name variable and all the labels will update to that language.

@name: '[name_en]';

#country_label {
  text-name: @name;
  ...
}

#place_label {
  text-name: @name;
  ...
}

Here are the current languages that Mapbox supports, their CartoCSS values, and what they look like on the map.

Language Value Preview
localized name
English name_en
French name_fr
Spanish name_es
German name_de

If you want to change all the labels to German, then update the variable like this:

@name: '[name_de]';

Keep in mind that some fonts will not have every character, so be sure to use the Places tab to see how your labels look in all areas of the world.

Remove labels or features

No matter what data you have in your project, layers will only show up on the map if you set a specific style for them. You can remove any layer or feature by not styling it. You can delete or comment out any style to remove it from the map.

For the Streets style, if you want to remove all the labels, you can delete the Carto tab labels. Use Ctrl+R (Command+R) to refresh your screen to preview or Save to see make the changes permanent.

But what if you only want to remove the road labels? Find the road label styles in the labels tab and delete them or comment them out. You’ll see your changes after you refresh or save.

Commenting out styles instead of deleting them is a good practice in case you want the style later.

Upload and publish

From the Settings panel, you can upload your style to your Mapbox account.

Your style will appear on your Classic styles page with a map ID, so you can use the style with our developer tools or just share the map right away.

Build a mapping app

With the map ID, you can use your style with any of our developer tools. Need to make your map interactive or want to add custom markers? Use Mapbox.js. Check out our Extending interactivity with Mapbox.js and Markers and Mapbox.js guides to get started.

Pushing to GitHub

We recommend that you track your Mapbox Studio Classic style with git and/or GitHub. When you upload your style to your Mapbox account, this is not a backup - it’s the processed style. If you lose the local copy of your style, then you cannot make any changes. Check out our Collaborating with Mapbox guide to learn the best practices for tracking your project with GitHub.

Next steps

Hooray! You created your first style with Mapbox Studio Classic! Here are more guides to help you style your map and add custom data:

Next article:

Getting started with Mapbox Studio Classic

Design radically custom maps with data powered by vector tiles in Mapbox Studio Classic. Let's get started!

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