Upgrade from Mapbox Studio Classic

Welcome to the new Mapbox Studio! This guide will walk through some of the things that have changed from Mapbox Studio Classic to Mapbox Studio and get you started making beautiful, custom maps.

Interface overview

How your maps work

The new version of Mapbox Studio implements several radical changes to how map styles are structured and created.

At the core of these changes is the switch from Mapnik to Mapbox GL as a rendering engine (for actually turning code and data into pretty maps in the browser) and from CartoCSS to Mapbox Style Specification as a styling language. These changes mean the experience of using Mapbox Studio will be a little different than Mapbox Studio Classic, but with a more intuitive interface and more options than ever before.

A new interface

The new Mapbox Studio is a web application and no longer needs to be installed on your desktop. This means it can be used across operating systems with fewer compatibility issues.

Browser compatibility:

  • Chrome
  • Firefox
  • Safari 8
  • IE 11

Mapbox Studio can only work in browsers that support WebGL.

add new layer

Edit layer color from direct select


With the switch to Mapbox GL comes not only a new interface, but also some new terminology. Mapbox Studio Classic had vector tile and raster image sources and CartoCSS styles that were rendered with Mapnik into image tiles when uploaded to your Mapbox account. The new Mapbox Studio works a little differently.

  • Data sources, like vector data and raster images, are called tilesets.
  • Representations of data, like symbols or polygon fills, are called layers and contain references to tilesets.
  • Collectively, the tilesets and the styling layers are called styles.

Instead of writing out the style in code, like you did with CartoCSS, Mapbox Studio has a visual interface that will manage the style for you, and it does that by adding, changing, and moving layers to style the associated tileset and create a full style.


A tileset in Mapbox Studio is a collection of raster or vector data, like sources in Mapbox Studio Classic. You can even use the same Mapbox-provided tilesets (Mapbox Streets, Mapbox Terrain, and Mapbox Satellite)!

Plus, instead of creating sources in one mode, uploading them, and then re-adding them in another mode, the new Mapbox Studio allows you to drop data files right into the browser (shapefiles, GeoJSON, KML, GeoTIFFs, CSVs, and others). Once they’re loaded, they’ll be converted into tilesets and can be styled right from there.

add new layer

Create a new layer and select tileset source.


The way to style different types of features in the Mapbox Studio style editor is by using layers. The Mapbox Studio style editor user interface handles layer creation for you, so your days of writing out your styles in CartoCSS code are over! Plus, this layer styling provides a many more options than were ever available in Mapbox Studio Classic.

Styling in Studio vs writing CartoCSS

The Mapbox Studio style editor is now a graphically-focused interface: instead of interacting primarily with a code editor, styles are created with a user interface. Under the hood, you’re actually creating a GL stylesheet.

CartoCSS vs Mapbox Style Specification

CartoCSS, the styling language of Mapbox Studio Classic, is a CSS-like language created to make map styling friendlier for designers with existing CSS skills. When processed by Mapbox servers, it’s compiled down to Mapnik XML, the native configuration language of Mapnik, for processing raster tiles. CartoCSS is fundamentally a compiled language: it can be turned into Mapnik XML, but not vice-versa. Mapnik was never aware that you were writing CartoCSS.

Mapbox Studio now uses Mapbox GL for rendering instead of Mapnik. Mapbox GL has one styling language: the Mapbox Style Specification. Instead of resembling CSS, the spec is a subset of JSON. And unlike CartoCSS, Mapbox GL styles are read by the renderer.


Select multiple layers and edit layer properties in groups.

Technical advantages

The move to Mapbox GL has several significant technical advantages. There’s no difference between the style and how it is interpreted, which means there are no potential performance problems in compiling styles. Also, the styles that are rendered by Mapbox GL can be manipulated in realtime with JavaScript and native APIs. And generally, the simplicity of Mapbox styles and the fact that they’re a subset of JSON means that it’s easy to programmatically produce them from other languages or from code.

Practical advantages

Like CartoCSS, the Mapbox Style Specification defines a language for writing map styles. Unlike Mapbox Studio Classic, in the Mapbox Studio style editor you never have to write style documents by hand. One of the most exciting things about Mapbox Studio is that you build your layers with the interface and the style is created for you!

(Remember, layers are the name for the different style objects that apply to different types of features in your data.)

The interface has tons of options for creating highly customized styles.

Fonts, sprites, and resolution independence

Custom fonts and sprites (icons) can be added for each style as font files and SVG files. With Mapbox Studio, they are automatically rasterized and generated into the right data for the map to use.

This is a small example of a larger change – we’ve put a lot of effort into making Mapbox Studio the best tool for multi-resolution rendering. Vector tiles are effortlessly rendered at 2x and 3x scales, and since we dynamically rasterize fonts and sprites in the cloud – and encourage the usage of vector SVG sprites – high-dpi maps will have high-dpi assets as well, which makes it a great tool for both web and mobile.

Example of a sprite

Fractional zoom

In Mapbox Studio Classic, it was common to write zoom-dependent CartoCSS rules to respond to the relative data density at different zoom levels. These rules were often the biggest part of a stylesheet, trying to control many different transitions as the map was zoomed in and out.

The Mapbox Studio style editor adopts zoom-dependent styling as a core part of the interface and styling language: every property you click on has a “Style by zoom level” option that allows you to manage zoom-dependent values quickly and cleanly. And because Mapbox Studio is rendering vector data in the browser, there aren’t hard jumps between zoom levels: there are smooth, continuous transitions between zoom levels, and you can set styles to fade gracefully from one to another!

multi layer ramp

Style by zoom level from the property panel.

Publishing your map

You can publish your Mapbox Studio style on the web with one of our JavaScript libraries or in your app with our mobile SDKs. Check out our Publish your Mapbox Studio map style to learn more!

Exploring brand new maps

Mapbox Studio opens doors for map designers, more than we’ve ever been able to open before. Check out the Mapbox Studio Manual and our Mapbox Studio tutorials to get started!