Map design

You can use Mapbox to control nearly every aspect of the map design process, including uploading custom data, tweaking your map’s color scheme, adding the perfect font, creating data-driven visualizations, and more. The core of the map design process is the style: a document, written in JSON, that defines exactly how your map should be drawn. Because all Mapbox styles conform to the open source Mapbox Style Specification, your maps can be rendered consistently across multiple platforms, including on the web with Mapbox GL JS, the Mapbox Static API, on mobile with the Mapbox Android and iOS SDKs, and with any third party libraries that are designed to read Mapbox styles. This guide explains how Mapbox styles work and where you can go to learn more and get started designing your map.

Style documents, or Style JSON, contain style rules that are used by a renderer to display the map you see in your browser or device. In this example, you can see references to the style’s data and images and instructions on how to render them in the Style JSON on the right and the rendered live map on the left. The map is displayed in your browser after Mapbox GL uses the style JSON and the tilesets it refers to to draw the final map.

How map styles work

Style JSON must be written according to a strict specification in order for the the renderer to interpret it and display the map in your browser.

Mapbox Style Specification

The Mapbox Style Specification defines the information that should be included in a style document in order for the renderer to display the map, including the title, values for the initial camera position, sources and other resources used in the style, and the styling rules for the map’s layers. The complete requirements are listed in the Mapbox Style Specification, but some of the key concepts to understand are:

The map that you see in your browser or on your device is the result of applying style rules (Style JSON) to data sources (usually map tiles or GeoJSON) in order to render a complete map. In the language of the Mapbox Style Specification, data sources are called sources and the style rules you apply to that data are organized into layers. You cannot create a map without specifying both sources and layers.

  • Sources. Sources tell the renderer what kind of data you would like to include and where to find it.
  • Layers. A layer is a styled representation of the data in a source. It includes information about how the layer should appear on the map, including color, opacity, font, and more.

If you are using any icons, images, or fonts in your map, your style will need to include a sprite or glyphs property.

  • Sprite. Any icons or images in your style will need to be stored in a sprite. Read more about how sprites work here.
  • Glyphs. Glyphs are used to display the fonts you are using in your style. A style’s glyphs property provides a URL template for loading signed-distance-field glyph sets in PBF format.

Styles vs. classic styles

While styles are created in Mapbox Studio and are written in JSON according to the Mapbox Style Specification, classic styles are made with Mapbox Studio Classic, a desktop application for designing classic styles, and are written in CartoCSS. The two are unrelated and incompatible – the renderers that work with one do not work with the other.

Styles work with Mapbox GL JS, the Mapbox mobile SDKs, and any third party software designed to read Mapbox styles. Style rules and tilesets are combined and rendered completely on the computer or mobile device that has requested them. Because styles are designed to work with GL-based renderers, you can alter your style programmatically after the map has been loaded.

Classic styles work with Mapbox.js, Leaflet, and any third party software that is designed to work with classic map tiles. Classic map tiles are rendered completely on Mapbox serves and cannot be altered programmatically once the map has been loaded.

Data-driven styles

Data-driven styles allow you to change a layer’s style based on properties in the layer’s source. For example, you might create a data-driven style rule that sets the color of states in the US based on the population of each state.

Graduated circle map: In a graduated circle map, the radius of the circle layer is a representation of the magnitude of data values. In this example, the color and radius of the circle layer changes based on the number of pedestrians at that intersection in the data.
Choropleth map: In a choropleth map, a 'fill' layer changes color based on data properties. In this example, the color of a state changes based on the population in the data.
Colored line map: In a colored line map, a line layer changes color based on data properties. In this example, the color of a flight path changes based on the difference between local time at the flight's origin and destination.
3D Building map: Using a fill-extrusion layer, extrude buildings in 3D based on data properties. In this example, the extrusion height of the building changes based on the "height" and "min_height" of the building polygon.

Required style sheet objects for data-driven styles

Each layer that uses data-driven styles can include the following items in their property functions:

  1. property : The data column name used for the data-driven style. Required
  2. type : One of “identity”, “interval”, “exponential”, or “categorical”. The type object specifies the property-function to use when calculating the data-driven style paint-property ranges.
  3. stops : An array of [value, color] pairs that correspond to the bin ranges to use for the property function. Functions with type: "identity" cannot include the stops property in their definition. Required unless type is “identity.”

Note: Zoom functions and property functions can be combined in the stops property. See zoom and property functions docs.

Property functions

Property functions allow the appearance of a map feature to change with its properties. Property functions can be used to visually differentiate types of features within the same layer or create data visualizations. Each stop is an array with two elements, the first is a property input value and the second is a function output value.

Property-function Description Example
exponential Return the output by interpolating between stops just less than and just greater than the function input. This is the default for continuous value data properties. Style a county fill-color by population, where the color continuously varies from red to blue between 0 and 10 million people.
interval Return the output value of the stop just less than the function input. This is the default for discrete value data properties. Style a county fill-color for average income into 3 color ranges [0-25 red, 25-75 middle, 75+ upper].
categorical Return the output value of the stop equal to the function input Style a circle by the ‘type of restaurant’ data column, which can have values of [‘fastfood’, ‘fastcasual’, or ‘finedining’]
identity Return the input Style transit data routes where color is an attribute in the datasource for each transit line.

Creating map styles

You can use the Mapbox Studio style editor to generate style JSON, write it directly, or use the Mapbox Styles API to read and change map styles, fonts, and images.

Mapbox Studio

The Mapbox Studio style editor is a visual interface for creating and editing a style according to the Mapbox Style Specification. You can learn more about how to create and edit styles in the Mapbox Studio Manual style section.

Mapbox Styles API

The Mapbox Styles API lets you read and change map styles, fonts, and icons. This API is the basis for Mapbox Studio. If you use Mapbox Studio, Mapbox GL JS, or the Mapbox Mobile SDKs, you’re already using the Styles API. You can learn more about the Styles API in our API documentation.

Mapbox Style Specification

You can create a style from scratch using a text editor and following the Mapbox Style Specification.