Map styles
You can use Mapbox GL JS to control many aspects of the map design, including styling custom data, tweaking your map's styling, adding fonts, creating data-driven visualizations, and more. You can use a map style designed by Mapbox's cartographers, such as Mapbox Standard, or create a custom map style by adjusting the map's colors, icons, and fonts to match your application's UI or company's brand.
Learn how Mapbox styles work and get started developing your map.
There are two approaches to customizing the look of the map:
- Update map features dynamically at runtime using Mapbox GL JS API. 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 custom 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.
These guides cover working with the map style at runtime. For more information on how to create a custom map style in Mapbox Studio, see the Mapbox Studio Manual.
Set a style
Across the Mapbox ecosystem, the appearance of the map is determined by the map style. A Mapbox style is a JSON object that defines exactly how to draw a map. It defines almost everything related to a map's appearance. In Mapbox GL JS, you can set the style of the map when creating the map instance or at any point afterwards.
Choose a style
The style you choose for your application should reflect how your users will interact with the map and what they will use your application for. If you are not sure what style is right for you, we recommend getting started with the carefully designed, all-purpose Mapbox Standard style.
Load a style
Mapbox GL JS’s Map
class provides an embeddable map interface. You can embed the map on a webpage, allow users to manipulate it with standard gestures, and more.
If you don’t specify a style when initializing a map, Mapbox GL JS will use the Mapbox Standard style by default.
You can rely on the default Mapbox Standard style, load the style when you first initialize the map by including it in the style
property of Map
options, or at any time after the map has been initialized using Map
setStyle
method by providing a corresponding style URL.
Mapbox Standard
Mapbox Standard is the default style, and instantiating a Map
without specifying any style means your map will use Mapbox Standard.
const map = new mapboxgl.Map({
container: 'map',
center: [-74.5, 40],
zoom: 9
});
Classic style templates and custom styles
If you don’t use Mapbox Standard, you can load your style by setting the style
property with your custom style URL.
const map = new mapboxgl.Map({
container: 'map',
style: '<STYLE_URL>',
center: [-74.5, 40],
zoom: 9
});
To use one of the Mapbox-owned styles, use one of the following values:
mapbox://styles/mapbox/standard
mapbox://styles/mapbox/standard-satellite
mapbox://styles/mapbox/streets-v12
mapbox://styles/mapbox/outdoors-v12
mapbox://styles/mapbox/light-v11
mapbox://styles/mapbox/dark-v11
mapbox://styles/mapbox/satellite-v9
mapbox://styles/mapbox/satellite-streets-v12
mapbox://styles/mapbox/navigation-day-v1
mapbox://styles/mapbox/navigation-night-v1
Though less common, you can also use a JSON value instead of a URL to load a style if you've written your style JSON manually.
You can also change the style any time after initializing the map using the
Map
setStyle
method. If you added
any layers at runtime, you will need to re-add layers after the new style is
loaded.
Configure a style
Depending on what map style you choose, you have different configuration options available to customize aspects of your style such as fonts, colors, and more.
Mapbox Standard
The underlying design paradigm to Mapbox Standard is different from what you know from the classic styles templates. We’re establishing the concept of a basemap; Mapbox Standard is the first Style to follow this paradigm. You can consider everything that is maintained by Mapbox (natural features, roads, buildings etc.) as the basemap into which you embed your custom layers. The difference between the basemap and custom layers is important because different styling rules apply to them.
To change the visual appearance of the Standard basemap, you need to use the setConfigProperty
method. Mapbox Standard offers 8 configuration properties that can be used to change the appearance of the basemap using setConfigProperty
:
Property | Type | Description |
---|---|---|
showPlaceLabels | Bool | Shows and hides place label layers. |
showRoadLabels | Bool | Shows and hides all road labels, including road shields. |
showPointOfInterestLabels | Bool | Shows or hides all POI icons and text. |
showTransitLabels | Bool | Shows or hides all transit icons and text. |
show3dObjects | Bool | Shows or hides all 3D layers (3D buildings, landmarks, trees, etc.) including shadows, ambient occlusion, and flood lights. |
theme | String | Switches between 3 themes: default , faded and monochrome . |
lightPreset | String | Switches between 4 time-of-day states: dusk , dawn , day , and night . Lights can also be fully customized beyond the presets using the Mapbox style specification. |
font | String | Defines font family for the style from predefined options. Options: Alegreya , Alegreya SC , Asap , Barlow , DIN Pro , EB Garamond , Faustina , Frank Ruhl Libre , Heebo , Inter , League Mono , Montserrat , Poppins , Raleway , Roboto , Roboto Mono , Rubik , Source , Code Pro , Spectral , Ubuntu , Noto Sans CJK JP , Open Sans , Manrope , Source Sans Pro , Lato |
Here’s an example illustrating how to switch the 3D lights in the basemap from the default preset, day
, to another preset, dusk
.
map.on('style.load', () => {
map.setConfigProperty('basemap', 'lightPreset', 'dusk');
});
Similarly, you can set other configuration properties of the Standard style such as showing POIs, place labels, or specific fonts:
map.on('style.load', () => {
map.setConfigProperty('basemap', 'showPointOfInterestLabels', false);
});
Other options to customize your map using Mapbox Standard include configuring root properties or styling your custom data in custom layers such that it reflects your personal preferences. Note that all the configurations are also available in the Mapbox Studio.
For custom layers that you add to the Mapbox Standard basemap, all configuration options are defined in the Mapbox Style Specification.
Use different configuration properties with Mapbox Standard Style.
Style imports
To work with styles like Mapbox Standard, we've introduced Style APIs that allow you to import other styles into the main style you display to your users. These styles will be imported by reference, so updates to them will be reflected in your main style without additional work needed on your side. For example, imagine you have style A and style B. The Style API will allow you to import A into B. Upon importing, you can set configurations that apply to A and adjust them at runtime. The configuration properties for the imported style A will depend on what the creator of style A chooses to be configurable. For the Standard style, 6 configuration properties are available for setting lighting, fonts, and label display options. To import a style, you need to add an imports property to your Style JSON. In the above example, you would add "imports" to your Style JSON for B to import style A and set various configurations as defined in style A in the schema root property.
...
"imports": [
{
"id": "A",
"url": "STYLE_URL_FOR_A",
"config": {
"font": "Montserrat",
"lightPreset": "dusk",
"showPointOfInterestLabels": true,
"showTransitLabels": false,
"showPlaceLabels": true,
"showRoadLabels": false
}
}
],
...
Mapbox Standard Satellite
The Standard Satellite Style (mapbox://styles/mapbox/standard-satellite
) combines updated satellite imagery and vector layers to offer users improved clarity and detail. Like Standard style, the Satellite Style receives all updates automatically and also supports light presets. Additionally, it introduces two new configurations showRoadsAndTransit
and showPedestrianRoads
. Users can now choose to hide roads, simplifying the map style for a better focus on specific areas or features.
The Standard Satellite style offers 8 configuration properties for developers to change when they import it into their own style:
Property | Type | Description |
---|---|---|
showRoadsAndTransit | Bool | Shows and hides all roads and transit networks. |
showPedestrianRoads | Bool | Shows and hides all pedestrian roads, paths, trails. |
showPlaceLabels | Bool | Shows and hides place label layers. |
showRoadLabels | Bool | Shows and hides all road labels, including road shields. |
showPointOfInterestLabels | Bool | Shows or hides all POI icons and text. |
showTransitLabels | Bool | Shows or hides all transit icons and text. |
lightPreset | String | Switches between 4 time-of-day states: dusk , dawn , day , and night . |
font | String | Defines font family for the style from predefined options. |
Important: Standard satellite style doesn't support theme
and show3dObjects
configuration.
Classic style templates and custom styles
The configuration options for classic style templates and custom styles are defined in the Mapbox Style Specification. Note that all the configurations are also available in the Mapbox Studio.
Work with layers
You can use Mapbox GL JS API to add more styled data to the map at runtime. There are two key concepts to understand when preparing to add a layer to a style at runtime: layers and sources. Sources contain geographic data. They determine the shape of the features you’re adding to the map and where in the world they belong. Layers contain styling information. They determine how the data in a source should look on the map.
A layer is a styled representation of data of a single type (for example polygons, lines, or points) that make up a map style. For example, roads, city labels, and rivers would be three separate layers in a map. There are several layer types (for example fill, line, and symbol). You can read more about layers in the Mapbox Style Specification.
Most layers also require a source. The source provides map data that Mapbox GL JS can use with a style document to render a visual representation of that data. There are several source types (for example vector tilesets, GeoJSON, and raster data). You can read more about sources in the Mapbox Style Specification.
In Mapbox GL JS, the Map
class exposes the entry point for all methods related to the style object including sources and layers.