Getting started with Mapbox Studio Classic

Mapbox Studio Classic is a desktop app for designing beautiful maps and converting custom data into compact vector tiles - the newer, faster map tile specification. Map data is hosted remotely as vector data, completely separate from the map style, which means smaller uploads, multiple style variations on the same data, and faster design iterations.

Shown left: source mode, shown right: style mode.

In source and style modes within Mapbox Studio Classic, you can accomplish two major tasks:

  • Create vector tiles using custom data you provide (source)
  • Design maps with CartoCSS using Mapbox or custom data sources (style)

This guide will cover both styles and sources and explain how to publish both of them to Mapbox.com. It will also cover how to style .mbtiles and map IDs from pre-processed vector tiles.

If you haven’t yet, download and install Mapbox Studio Classic before moving forward.

Style

Styles are the design rules that customize the display of your maps. Mapbox Studio Classic styles are written using a language called CartoCSS, which assigns certain styles (like color, line-width, opacity, etc.) to each vector data feature at specified zoom levels.

Mapbox Studio Classic comes pre-loaded with three Mapbox-curated vector tilesets – Mapbox Streets, Mapbox Terrain, and Mapbox Satellite. Style these tilesets right out of the box or complemented with your own custom data.

Data sources and design styles are independent; the same style can be applied to different data sources and the same data source can power different styles. This makes iterative map designing fast and efficient.

Different map styles using the same Mapbox Streets vector tile data source

Start a new Style

Mapbox Studio Classic ships with 16 starter styles for you to use or customize for your final map designs. Simply launch Mapbox Studio Classic, click the Styles & Sources link on the bottom left (below your account photo). Here you can choose a starter style to serve as the base for your map designs. Starter styles make styling your maps faster and to help you learn CartoCSS.

Here is a general overview of the characteristics of each of the 16 starter styles Mapbox Studio Classic ships with. This will help you determine which start to begin designing your map with.

Simple styles

Basic, Mapbox Dark, and Mapbox Light are good basemaps for adding interactivity or custom data. These are also good maps to start with to learn CartoCSS. Only some available data layers from Mapbox Streets are included in these styles, but you can easily add more layers for more advanced styling.

Basic, Mapbox Dark, and Mapbox Light

Navigation styles

Emerald, OSM Bright, Streets, and Streets Classic are great basemaps for transportation or navigation based projects. These maps style all Mapbox Streets data layers and include heavily commented CartoCSS which explains what is happening in the style.

Emerald, OSM Bright, Streets, and Streets Classic

OSM Bright focuses on styling every feature available in Mapbox Streets (curated OpenStreetMap data).

Emerald differentiates roads and highlights global transportation networks.

Terrain styles

Mapbox Outdoors and Run, Bike, and Hike are great starters for outdoors-based projects. Take a look the CartoCSS – if you want to use this treatment on another style just copy and paste the code and make sure to add the remote source map ID for Mapbox Terrain.

Mapbox Outdoors and Run, Bike, and Hike

Differentiate class=path for roads, bridges, and tunnels styling type options: footway, path, hiking, trail, cycleway, mtb, piste, and other.

These styles contain gently styled landcover, contours, and hillshades.

Satellite / raster styles

Looking for satellite image data? Satellite Afternoon and Streets + Satellite feature Mapbox Satellite raster (vector) tiles. Study the CartoCSS used in these styles to modify raster imagery, composite raster and vector tile data, and explore composite operations in Mapbox Studio Classic.

Streets + Satellite and Satellite Afternoon

Stylized styles

The rest of the starter styles are highly stylized maps that use a wide variety of patterns, textures and custom fonts. Test these out to find ideas or start your own stylized map design.

Wheatpaste, Pirates Return, Pencil, High Contrast, Comic!

Take the style tour

Once you have selected a starter style, take the tour! Click Docs then Interface tour to get to know Mapbox Studio Classic’s styling features and how to navigation the interface.

Style interface

Let’s review the interface for Mapbox Studio Classic’s style mode. On the far left are all of the project’s settings, the center contains the live preview of your map, and the CartoCSS panel is on the right.

Basic CartoCSS

Mapbox Studio Classic uses CartoCSS to style maps - it’s like CSS for map design. CartoCSS uses the map’s individual data layers to select and assign properties and values to them.

CartoCSS syntax looks like this:

#layer {
  property: value;
}

Read more about adapting starter styles with CartoCSS, take a deep dive into CartoCSS, or start a style tutorial with the links below:

Source

Sources are the underlying vector data that is powering your map styles. You can import your own custom data in a variety of supported formats and pack layers, geometries, and feature attributes into lower zoom levels as vector tiles in Mapbox Studio Classic. Then you can upload and store the vector tiles for remote access on Mapbox.com.

Once uploaded, you can style the vector tiles by using their map ID either in Mapbox Studio Classic or for styling with the Mapbox Style Specification combined with Mapbox GL JS API functionality.

Custom data converted to vector tiles, composited with Mapbox data, and then styled.

Start a new Source

Create vector tiles by starting a new blank source project. Click on Blank source from the New style or source panel in Mapbox Studio Classic.

Source interface

The source interface contains, from left to right: Project settings, live preview vector data, and data layers with values, attributes, and connection information.

Settings overview

From the Settings panel, you can upload your source to your Mapbox account. Your source will appear on your Data page with a map ID which you can then style. You have a few options in Settings: upload to Mapbox.com, host locally, export .mbtiles (vector sources), and center your map location for this file.

  • Click the Upload to Mapbox button to upload and update your remote source on your Mapbox account. A map ID is created for each new source, which you can use to add the vector tiles back to Mapbox Studio Classic for styling.

  • Host vector data locally rather than upload it to Mapbox.com by clicking the Create style from source link. Use a local source to test your data as you enhance and style iteratively.

  • Click Export to MBTiles to download a .mbtile locally which you can upload via the Mapbox Uploads API.

  • Click the lock icon next to the center field to save map location at current center point and zoom. Next time you open this source file, you’ll be in the same spot. Make sure to move and zoom to the location you want before you click to save that location.

Add custom data

You can add as many layers of data as you want to create a single vector tileset. For each layer, click New layer button and add your new data source.

Browse your computer for any of the various supported data formats as your uploaded data source.

Configure your data

Once data is loaded into the live vector data preview, set Configure options for your data. Check the Fields tab to see your data attributes in this source. And click Done, when you’re ready to complete the process. Walk through this process with an example data source in Studio source quickstart.

Click the zoom to data icon if you can’t locate your data or want to jump back and forth between layers.

Keep tiles small

Sometimes, adding too many data layers or having too much data density can cause upload errors. If you see an orange alert over the current zoom in the top right of the Mapbox Studio Classic interface after loading your data, click it to see more details on the error.

The number to the left of the zoom shows the average size per tile based on the tile you’ve viewed in the live preview. Move your mouse around to different parts of your map, zooming in and out, to get a better sense for where your data is too heavy.

Converting thousands of points into vector tiles is a helpful read if you’re struggling with point data uploads. The section on Data to vector tiles contains tips that can help trouble-shoot any data source upload.

Minzoom and maxzoom

Setting proper minzoom and maxzoom values is crucial to creating size appropriate vector tiles. Your tiles must be smaller than 500kb each to upload successfully to Mapbox.com. Set these values accordingly to ensure upload success.

minzoom determines at which zoom level data will first appear. maxzoom determines the zoom level data will be last stored. Data still appears beyond this zoom, thanks to overzooming, so make sure it’s visually accurate at this maxzoom.

More on setting minzoom and maxzoom values and working with larger data files here:

Publish

Finalize your styles and sources by uploading them to your Mapbox account. Under the Settings panel in both modes in Mapbox Studio Classic, you’ll find a big blue button that makes your maps and data live online.

Once uploaded, share a link to your map style by clicking the arrow icon. You can also see how many map views your map has received by clicking the chart bar graph icon.

Composite styles in Editor

You can also composite your map styles in Editor.

In Editor, you can add markers, lines, and polygons and share your project. You can also add your style to any other Editor project as a data layer.

Style sources in Mapbox Studio Classic

After uploading to Mapbox.com, each data source is given a unique map ID which you can see on your account data page. Click the clipboard icon next to the map ID to copy it. To use it in Mapbox Studio Classic, you need to paste it into a New Style project.

In Mapbox Studio Classic, open and save a New Project.

In your New Project, select Layers, click the Change source button, and paste the map ID. To composite your source, add a comma to the end of the current map ID then paste your map ID (with no space) after the comma.

Save, then click the x-ray button and navigate to the location of your data to see it.

Read more about compositing sources in the Style Manual.

View and style .mbtiles

You can upload .mbtiles directly to Mapbox.com to style them in Mapbox Studio Classic. Go to your Mapbox.com account uploads page, and upload your .mbtile file. After it’s processed you will have a map ID to use to style your map with in the process outlined above.

Next steps

We’ve covered the basics of Mapbox Studio Classic, styles, sources, the interface, and upload tips. Now you can start getting to know CartoCSS for styling your sources or dive deeper with some more advanced map design topics.

Next article:

Use pro fonts in Mapbox Studio Classic

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