Map design and styles
You can use Mapbox tools to control many aspects of the map design process, including uploading custom data, adjusting 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 style with Mapbox tools as well as more advanced concepts for in-depth customization.
The map below showcases the Mapbox Standard style, which you can use as a base map in your applications. You can learn more about the features of this style in the Mapbox Standard section of this guide.
In the Mapbox ecosystem, a map is an interactive element that you can add to a webpage or mobile app to display styled geospatial data. A style is a configuration document that defines the visual appearance of a map.
When showing a map, a style is required. Mapbox maps will default to using the Mapbox Standard Style if you do not specify a style. Styles can be modified after the map loads, for example you can add and remove data layers from a style at runtime to update the map.
How do I make a map style?
There are multiple ways to craft a map style that makes your data shine: You can make a custom style by adding your data on top of the Mapbox Standard style, 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
Classic styles
You can build a custom map style from scratch using the Mapbox Studio style editor. You can use Mapbox's streets-v8 tileset as a data source, or you can upload your own data to Mapbox and use it in your style.
Continue to the section What is a style to learn about the concepts required to work with custom styles.
Methods for customizing a map style
Whether you use Mapbox Standard or a custom style, there are two main approaches to customizing the look of the map style:
- Update map features dynamically at runtime using the Mapbox GL JS or the Mobile Maps SDKs. 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
layoutandpaintproperties 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 an interactive element you can add to a webpage or mobile app to display styled map data. 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 consistent rendering across 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.
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.
Follow this tutorial to learn how to create a custom style in Mapbox Studio.
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://stylesis an alias for the Mapbox Styles API endpoint.owneris the username for the Mapbox account that owns the style. To use Mapbox-owned styles, theownervalue should bemapbox.style_idis 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.
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 () 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:
| Platform | Mapbox-owned style | Custom style |
|---|---|---|
| Web | Display a map on a webpage | Display a map with a custom style |
| Android | Create a simple map view | Mapbox Studio style |
| 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.
- The
getexpression retrieves the value of the'marker-number'property from the data. - The
matchexpression 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.