Skip to main content

Map design and styles

Additional Developer Resources

You can use Mapbox to control many aspects of the map design process, including uploading custom data, tweaking your map's styling, adding fonts, creating data-driven visualizations, and more.

In this guide, you'll learn about the basic principles of making a map with Mapbox tools as well as more advanced concepts for in-depth customization.

How do I make a map?​

There are multiple ways to make a map that makes your data shine: You can use Mapbox Standard style, our Mapbox classic style templates, or build a custom style completely from scratch.

Mapbox Standard​

Mapbox Standard is our latest 3D mapping experience featuring dynamic lighting capabilities, landmark 3D buildings, and more. Beyond introducing a high-quality visual experience, Standard also reduces the technical burden and cartographic ability needed to maintain a map and allows Mapbox to deliver the latest data and design updates to your base map style without a manual upgrade that risks breaking changes.

Key features​

3D lighting presets
Carefully designed lighting & shadow presets (Day, Night, Dusk and Dawn) and ability to pass custom lighting settings.
3D landmarks and buildings
High-fidelity 3D landmarks with styled windows, walls & roofs and entrance lights as well as extensive global coverage for non-landmark buildings.
3D vegetation and terrain
Detailed 3D vegetation modeled to reflect different geographic biospheres across the globe accurately and 3D terrain.
Automatic updates
A versionless style identifier to bring automatic updates, such as continuous styling, feature and data updates to the style without requiring manual updates.
Simplified configuration
Simplified interface for key styling configurations in runtime and Studio.
Core 2D data features
All the core data features from our classic styles, such as detailed iconography, place labels, admin boundaries, highly organized road network data, and more.

Mapbox classic style templates and custom styles​

The 5 Mapbox classic style templates are tailormade for different use cases.

Mapbox also offers the option to use classic style templates to make a map, or you can build a custom map style completely from scratch using the Mapbox Studio style editor. Starting from classic style templates or a custom style if you have experience with map design or would like to invest more in learning about it.

Working with custom styles

Continue to the section What is a style to learn about the concepts required to work with custom styles.

Tools for making a map​

Whether you use Mapbox Standard, classic style templates or a custom style, there are two approaches to customizing the look of the map:

  • Update map features dynamically at runtime using the Maps SDK. Lighten or darken the map based on the time of day, personalize icons and map colors based on your users’ activity, switch languages dynamically, or increase the size of labels based on user preferences to improve legibility.
  • Create a map style with Mapbox Studio. Upload data, build styles from scratch, and style groups of layers together using style components. Publish your custom style and load it into your application. If you update the underlying data or you edit and publish updates to the style in Mapbox Studio, those changes will be reflected in your application.

These approaches are not mutually exclusive. You can load a custom style and update map features from that custom style in your application at runtime.

If you prefer working in a visual interface, or if you want to add custom tilesets to the style, consider using the Mapbox Studio style editor to maintain your style. If you intend to make small visual changes and if you need to add your data dynamically at runtime, consider changing features dynamically at runtime.

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.

These four custom map styles feature line traces, weather data, custom fonts, and 3D terrain. Learn more about popular use cases for custom map styles on our maps page.

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.

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 custom style​

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

circlecirclecircle
arrow-leftarrow-rightrotate
heartmapboxmenu

You can use the Mapbox Studio style editor to create and edit custom styles. Learn more about this web-based application in the Mapbox Studio manual.

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/styl@site/src/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.

How to find a style URL in Mapbox Studio

Need to find the style URL for one of your own custom styles?1. Log into your Mapbox account.2. Visit your Styles page in Mapbox Studio.3. Click on the ellipses menu (options) next to the style to see its style URL.

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:

PlatformMapbox-owned styleCustom style

globe Web

Display a map on a webpage

Display a map with a custom style

android Android

Create a simple map view

Mapbox Studio style

ios iOS

Create a simple map view

Apply a style designed in Mapbox Studio

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 instructions in these tutorials:

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.

Additional Developer Resources
Was this page helpful?