Mapbox Studio Classic style manual

This manual is a comprehensive overview of styling features, data referencing and ordering, CartoCSS, and rendering final map styles as high resolution image exports or published basemaps prime for interactivity. Let’s get started!

Style project

A Mapbox Studio Classic style project is stored in a single directory with a .tm2 file extension. A typical style project directory looks like this:



  • project.yml is the main project file in YAML format. This file contains the core metadata to the project as well as a reference to its vector tile source and the CartoCSS stylesheets it uses.
  • project.xml is a compiled, ready-to-publish mapnik XML file for the project. It can be used directly with tilelive-vector to render the style project as a map.
  • style.mss and any other mss files are CartoCSS files used by the project.
  • .thumb.png is a thumbnail image that serves as a quick preview of the project.
  • images and any other assets used by a project should be kept in the project directory so that it is portable.

Size limits

In order to keep all of our custom maps fast and responsive for everyone, there are several limits in place on the styles that you upload:

Tiles and file sizes

  • Individual tiles must be under 100kb
  • Individual tiles must be able to be rendered into pngs in 1sec (1000ms)
  • Average rendered tile must be under 50kb
  • Average rendering time must be less than 300ms
  • Unzipped project.xml must be under 750kb

Overall project uploads

  • Upload size should not exceed 750KB
  • Unzipped size should not exceed 5MB
  • Zipped .tm2z file must be under 500kb

Keep styles low

If you run into any of the errors above, try the following methods:

  • Include only essential files; extra fonts and imagery can weight down your files
  • Lower the number of PNG colors or JPEG quality in your project settings
  • Separate data layers with heavy filtering into “sub-layers” using attachments

Data sources

Mapbox Studio Classic map styles are built by accessing vector tile data sources. Separating the data source from the design allows for faster design iterations paired with full global data coverage without lengthy downloads, imports, or time spent tuning database queries. Vector tiles define a protobuf schema that can pack layers, geometries, and feature attributes from any datasource into individual vector tiles and render the original datasource no longer necessary.

Referencing sources

Every Mapbox Studio Classic map style must have a vector tile data source. Studio styles come with Mapbox Streets source by default. You can swap out and composite custom sources that you’ve uploaded to your Mapbox account.

If you have been working on styles for streets in London and want to check how well your styles apply to data in Paris, Mapbox Studio Classic will download the vector tiles on-the-fly as you pan over to France. Mapbox Studio Classic caches downloaded vector tiles to an MBTiles database on disk so that you can take your work offline in a limited fashion.

Remote sources

You can change the source of a Mapbox Studio Classic style by opening the Layers panel and clicking Change source. You will be shown a list of the vector tile sources that you’ve uploaded to your Mapbox account.

Mapbox also provides some ready-made sources that you use to design your own custom styles. Documentation is available explaining the data provided by these layers and tips for styling them:

Compositing sources

You can merged together multiple vector tile sources into a single source if they are coming from the Mapbox API. For example, you can combine up-to-date OpenStreetMap data from Mapbox Streets with a custom overlay of your own data.

To do this, open the Layers panel then click Change source. Eg:


Local sources

For complex vector tile sources, you might find it helpful to develop both the source and the style at the same time. Mapbox Studio Classic style projects can also reference local .tm2source projects as vector tile sources, so that you can quickly see changes without having to export or upload them.

To reference a local source, open the Layers panel, click Change source, then toggle from Remote to Local. You’ll be shown a list of all your local .tm2source projects that you can select from.

Local sources will not work in packaged and uploaded styles. Make sure to upload your source project in Mapbox Studio Classic and change the reference in your style project before you publish the style.

Controlling data order

Data - sources, layers, objects, and symbols - are drawn using a Painter’s Algorithm in Mapbox Studio Classic. This means that everything is drawn in a specific order, and things that are drawn first might be covered by things that are drawn later. The order in which objects are drawn depends on the following conditions.

  1. Priority: “Higher” layers obscure “lower” ones.
  2. Layer order: by default, layers in Mapbox Studio Classic are drawn bottom up based on how they are stored in the vector tile. This can be manually defined, with custom layer ordering.
  3. Attachment order: within a stylesheet, attachments you set (eg, ::glow { ... }) are ordered from top to bottom.
  4. Symbolizer order: you can add multiple property instances on the same object (eg a/line-color: blue; b/line-color: red;), these are drawn in the order they are defined.
  5. Data source order: the order in which you define your data sources decide the order they and their layers are drawn.
  6. Custom layer ordering: alter the order in which your data source layers are drawn by manually editing the project.yml file in your .tm2 folder.
  7. Data ordering with PostGIS: manipulated how the data in your custom data source with SQL and PostGIS.

Order vs. priority

For things like lines and areas, objects that are drawn first are less likely to be fully visible. Objects high in the stack might completely obscure other objects, thus you might associate these with a high ‘priority’ or ‘importance’.

However, for elements like text, markers, and icons things work a bit differently. They have their allow-overlap properties set to false (the default). Objects that are drawn first are more likely to be visible; instead of letting things sit on top of each other, overlapping objects are skipped. Since such objects higher in the stack are less likely to be drawn, you might associate these with a low ‘priority’ or ‘importance’.

Layer order

In Mapbox Studio Classic, layers are rendered in order starting at the bottom of the layers list moving up. If you look at the layers in the Mapbox Streets vector tile source you can see that the basic parts of the map (eg. landuse areas, water) are in layers at the bottom of the list. The things that shouldn’t be covered up by anything else (eg. labels, icons) are in layers at the top of the list.


Attachment order

Within a layer, styles can be broken up into ‘attachments’ with the :: syntax. Think of attachments like sub-layers. Add attachment to data layers with heavy filtering to keep file sizes low.


#layer {
  ::outline {
    line-width: 6;
    line-color: black;
  ::inline {
    line-width: 2;
    line-color: white;

Attachments are drawn in the order that they are defined, so in the example above the ::outline lines will be drawn below the ::inline lines.

Note that all styles are nested inside attachments. If you don’t explicitly define one, a default attachment still exists. Thus the following style produces the same result as the one above.


#layer {
  ::outline {
    line-width: 6;
    line-color: black;

  line-width: 2;
  line-color: white;

Symbolizer order

Each layer can have multiple symbolizers applied to it. That is, a polygon might have both a fill and an outline. In this case, the styles are drawn in the same order they are defined.

In this style, the outline will be drawn below the fill:


#layer {
  line-width: 6;
  polygon-fill: #aec;
  polygon-opacity: 0.8;

In this style, the line is drawn on top of the fill:


#layer {
  polygon-fill: #aec;
  polygon-opacity: 0.8;
  line-width: 6;

It’s also possible to create multiple symbols of the same type within a layer using named instances. Like attachments, their names are arbitrary.


#layer {
  bottomline/line-width: 6;
  middleline/line-width: 4;
  middleline/line-color: white;
  topline/line-color: red;

Note that symbolizer ordering happens after all other types of ordering - so an outline might be on top of one polygon but beneath a neighboring polygon. If you want to ensure lines are always below fills, use separate attachments.

Data source order

The order in which your data sources are listed in Mapbox Studio Classic also influences rendering order: data from sources are rendered in order. So if you click Change source and you see your.mapid,mapbox.mapbox-terrain-v2, the layers from mapbox.mapbox-terrain-v2 will render last, over the layers from your.mapid. To ensure that your own data renders last, use mapbox.mapbox-terrain-v2,your.mapid.

Custom layer order

You can change the layer order of any remote vector tile data source by manually editing the project.yml. Open a style’s project.yml file in a text editor and then add each layer’s {id} in top-down stacking order. Clone layers by listing {id}.{class} where {class} can be any word you choose to describe that layer.

Example below specifies layers from Mapbox Terrain (v2) and Mapbox Streets (v6) vector sources with the contour layer cloned:

source: "mapbox:///mapbox.mapbox-terrain-v2,mapbox.mapbox-streets-v6"
  - landcover
  - landuse
  - contour.line
  - hillshade
  - contour.label

Layers are stacked on the map top-down based on the project.yml list, however once in Mapbox Studio Classic the stack is listed bottom-up.


Data source is now locked in Mapbox Studio Classic since custom layer order defined, additional changes must be done manually in project.yml.

Note: After making edits to the project.yml file in a text editor, 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.

Mapbox data layers

Check Mapbox data layers using the Mapbox API .json file links below:

Use this format to check your vector tile data:{mapid}.json?access_token={your-access-token}

Note: Raster tile sources, such as Mapbox Satellite, must be combined with a vector source to list layer values in the API.

Data order with PostGIS

The order that your data is stored/retrieved in is also significant. The ordering of objects in the Mapbox Streets vector tiles have been optimized for the most common rendering requirements.

If you are creating a custom vector tile source this is something you will have to consider. When styling city labels, for example, it’s good to ensure that the order of your data makes sense for label prioritization. For data coming from an SQL database you should ORDER BY a population column or some other prioritization field in the select statement.

Data coming from files are read from the beginning of the file to the end and cannot be re-ordered on-the-fly by Mapbox Studio Classic. You’ll want to pre-process such files to make sure the ordering makes sense.

You can do this from the terminal with ogr2ogr. This example rearranges all the objects in cities.shp based on the population field in descending order (highest population first).

ogr2ogr -sql \
  'select * from cities order by population desc' \
  cities_ordered.shp cities.shp

For more on PostGIS and data ordering, check out Controlling label density in our PostGIS Manual.


Mapbox Studio Classic styles are defined using CartoCSS. A quick introduction to the language and a full reference list of properties are built into Mapbox Studio Classic from the Docs panel.

If you’re new to CartoCSS, Intro to Studio and CartoCSS is a great place to start.

Export for printing

With vector tiles, Mapbox Studio Classic maps are print ready. The resolution independence of vector tiles now makes it possible to create a map with flexible resolution appropriate for high quality printing. Now your data doesn’t just scale, it renders across all media in sharp detail.

Download print ready images in Mapbox Studio Classic through the export pane, integrated into the style pane for quick styling of print areas. You choose between three different paradigms for selecting the export area based on use case: dimensions in pixels, dimensions in inches, and geographic area. Export PNG and JPEG images at 150, 300, and 600 ppi.

Read up on our Web to Canvas Printing blog post for a walk-thru of the process.

UTFGrid interactivity

UTFGrid interactivity can be added to style projects by manually editing the project.yml file and filling out these additional fields:

  • interactivity_layer: the ID of the layer that should be made interactive.
  • template: a UTFGrid html/mustache template used to display data on tooltips.

Check out an example of this in action in our Style Quickstart.

Publish styles

Mapbox Studio Classic styles are packaged into .tm2z files for publishing on The package contains only the styling information and no data and thus is relatively small. Inside it are:

  • project.xml - the Mapnik-ready XML style definition automatically built by Mapbox Studio Classic from the project’s CartoCSS files and project.yml
  • .png, .jpg, and .svg files, unless they begin with an _

All other files are omitted from packaging. A .tm2z file should not be used as a backup of your .tm2 project as the original CartoCSS styles are not stored in it or recoverable from it.

If you have any source files (Photoshop/Gimp/Illustrator/Inkscape documents, mockups, reference files, etc) that are not directly required to render the style, they should be named beginning with an underscore or kept in a subdirectory beginning with an underscore. Mapbox Studio Classic will ignore such files & folders when creating packages to deploy for rendering.

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