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.
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. 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
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 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.
Required style sheet objects for data-driven styles
Each layer that uses data-driven styles can include the following items in their property functions:
- property : The data column name used for the data-driven style. Required
- 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.
- 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
stopsproperty 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 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.
|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
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.
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.