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 fonts, creating data-driven visualizations, and more.

In this guide, you'll learn:

• What styles are
• How styles work
• How to create a style
• How to use a style
• How to use data in your styles
• How to handle attribution and terms of service requirements

Key terms

It can be helpful to understand key terms related to map design. For more detailed definitions, click the terms below or visit the Glossary.

• Mapbox GL: a suite of libraries for embedding customizable maps in web, mobile, and desktop applications.
• Mapbox Studio style editor: a visual tool for creating a valid style document.
• Mapbox Style Specification: an open source standard defining a valid style.
• source: supplies the geospatial data that Mapbox GL displays on a map. Sources do not contain any styling information and must be combined with a style layer to appear on a Mapbox map.
• style: in Mapbox, a JSON object describing visual properties for map data.
• style layer: in Mapbox, a subset of data and styling instructions in a map style.
• style component: in Mapbox, a group of map layers that you can style as a single unit.

What is a style?

A Mapbox style is a JSON object that defines exactly how a map should be drawn. It defines almost everything related to a map's appearance.

A style document must contain the following:

• References to sources containing geospatial data. For example, a style might use a URL for a GeoJSON source or a tileset ID for a tileset source. Except for raster tiles or georeferenced images and videos, sources are pure data with no inherent visual appearance.

• Style layers give sources a visual appearance by specifying which layout and paint properties Mapbox GL should apply. These properties include colors, fonts, line widths, layer order, and more.

It may also include glyphs and sprite properties. These properties work automatically when you create a style with the Mapbox Studio style editor. In most cases you do not need to change them. The glyphs property tells the Mapbox map where to fetch fonts. The sprite property tells the Mapbox Map where to look for icons.

Every map depends on a style, so when you change a map style, any map that uses that style will be affected by your changes upon its next load.

Continue reading to see an example of a style document and learn how styles work.

What is a map?

A Mapbox map is a program you can add to a webpage or mobile app. It comes with many powerful functions and configurable options that you can use to use to make each map instance look and behave exactly as you want. A Mapbox map's style is one of its many configurable options, but is the one that will have the greatest impact on how your users perceive your map.

Here is one example of a map, and the code that creates it:

const map = new mapboxgl.Map({
  container: 'map',
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-74.5, 40],
  zoom: 9
});

Besides having a visual appearance, every Mapbox map also has powerful built-in functions that you can use to add interactive features to your maps or create data-driven visualizations.

For example, you can use a map's functionality to change its style from 'Light' to 'Dark' after sunset in a user's location; you can color election precinct polygons according to vote totals from a live data API; or you can enable users to show or hide map layers to visualize air quality data or weather information.

You can learn more about building interactive maps in our web applications and mobile applications getting started guides.

Example of a style and map

Below is a complete style JSON for a custom map style, and a map rendered using that style:

Inside the style JSON, you can see many layer definitions, including a background layer with a beige color property, a fill layer for national parks, and a line layer for waterways.

On the map, you can see the visual rendering of these layers. You can also interact with the map using pan, zoom, and tilt actions that are handled by the map object, not the style.

How styles work

A Mapbox style must conform to the Mapbox Style Specification, an open source standard that enables Mapbox GL to give consistent rendering instructions to many different clients, like web browsers, mobile or embedded devices, or third party libraries or applications designed to read Mapbox styles.

Tools like Mapbox GL JS and the Mapbox Maps SDKs for Android and iOS use Mapbox GL to combine style rules and data sources to render the resulting map completely on the computer or mobile device that has requested it.

Because styles are designed to work with GL-based renderers, you can change your style programmatically after the map has been loaded. This ability, known as runtime styling, gives you the ability to build highly controlled map interfaces, visualizations, and experiences using Mapbox.

You can learn more about Mapbox technology in our Introduction to Mapbox getting started guide.

How to create a style

Anyone can create a custom Mapbox style. This section describes two approaches for this task: using Mapbox Studio, or writing a style manually.

Use Mapbox Studio

You can use the Mapbox Studio style editor, a visual map style editor that works in your web browser, to create and publish your own custom styles. When you use this method, your style will automatically adhere to the required Mapbox Style Specification, and is automatically hosted on Mapbox servers.

With the style editor, you can create and edit style layers to control every aspect of a feature's appearance. Most Mapbox styles include style components, which allow you to edit groups of related layers like 'Roads' or 'Places' simultaneously.

To add custom data to you style, use Mapbox Studio or the Mapbox Tiling Service to upload data to your account.

For step-by-step instructions on using Mapbox Studio to create styles, follow these tutorials:

To learn more about publishing your styles, including information on using draft or production modes, refer to the Mapbox Studio manual.

Write a style manually

You can also write a style document manually and then upload it to your Mapbox account using the Mapbox Styles API. They Styles API also 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.

If you write your own style document, you can make sure that it conforms to the Mapbox Style Specification using the Mapbox style utilities npm package

How to use a style

This section will explain how Mapbox style IDs and style URLs work, and show how you can use them to reference Mapbox styles in a web application, mobile application, or third-party library or application.

Style URLs

A style URL is a shorthand notation for a Mapbox Styles API request.

Mapbox style URLs follow this format:

mapbox://styles/{owner}/{style_id}

The URL contains three pieces of information, separated by forward slashes (/):

• mapbox://styles is an alias for the Mapbox Styles API endpoint.
• owner is the username for the Mapbox account that owns the style. To use Mapbox-owned styles, the owner value should be mapbox.
• style_id is the unique style identifier (id) for the style.

The Mapbox GL client libraries use the style URL you supply to request the right style document from the Mapbox Styles API.

For example, this style URL...

mapbox://styles/mapbox/streets-v12

...makes an API request like this:

https://api.mapbox.com/styles/v1/mapbox/streets-v12?access_token=YOUR_MAPBOX_ACCESS_TOKEN

If you want, you can copy the API request above and paste it into your browser to test the validity of the request. Remember to replace any instances of YOUR_MAPBOX_ACCESS_TOKEN with your own Mapbox access token.

Using style URLs

Now that you know what a style URL is, you are ready to learn how to use one.

If you are adding a Mapbox map to a web or mobile application, you will most often use a style by copying its style URL and pasting it into the map initialization block in your app.

It's important to note that there are two kinds of styles:

• Mapbox-owned styles are professionally designed styles that are freely available for developers to use. You can learn more about these styles in our Mapbox Styles API documentation.

• Custom styles are styles that you create yourself, or that are shared by other Mapbox users. You can use a custom style if it is published, and you either own the style or have the correct permissions to access it.

The table below offers code examples showing how to use both kinds of styles in web and mobile applications. Click a link to view an example:

Other sharing options

Both Mapbox-owned styles and custom styles designed in Mapbox Studio come with a built-in WMTS endpoint that you can use to add your styles to desktop GIS applications like ArcGIS Online, Tableau, CARTO, and Fulcrum.

You can learn about this WMTS endpoint and other sharing options like Leaflet in the Mapbox Studio manual.

Data-driven styles

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

Here are some examples of data-driven styles using different layer types:

How to use expressions

You can use expressions to define the value of any layout property, paint property, or filter within a style. With expressions, you can style data with multiple feature properties at once, apply conditional logic, and manipulate data with arithmetic and string operations for a more sophisticated relationship between your data and how it is styled.

For example, the code snippet below uses two expressions to set the value of the layout property icon-image.

1. The get expression retrieves the value of the 'marker-number' property from the data.
2. The match expression displays a 'pin-red' icon image for features matching the 'marker-number' value of 'one', a 'pin-blue' icon image for 'two', a 'pin-green' icon image for 'three', and a 'pin-white' icon image for any other values.

"layout": {
  "icon-image": [
      "match", ["string", ["get", "marker-number"]],
        "one",
        "pin-red",
        "two",
        "pin-blue",
        "three",
        "pin-green",
        "pin-white"
      ],
  "icon-size": 1
}

You can read the expressions documentation in the Mapbox Style Specification to learn about the different kinds of expression operators you can use, like lookup, decision, or math operators. You can also learn to use expressions by following step-by-step instuctions in these tutorials:

• Get started with Mapbox GL JS expressions
• Make a heatmap with Mapbox GL JS

Attribution and Terms of Service

Whether you're creating a custom style with Mapbox Studio or building a mobile app with the Android SDK, all Mapbox tools are governed by our attribution requirements and our terms of service. For more information about either of these requirements, contact Mapbox Support.