Mapbox Styles
- Highly performant global basemaps
- Powered by Mapbox's global vector tilesets and raster tilesets
- Customizable/configurable with Mapbox Studio
A Mapbox map style defines how a map is rendered — including what data sources to use, which layers to display, and how each layer should be styled. Styles are the foundation of every Mapbox map.
Styles are a cross-platform concept and can be used across all Mapbox SDKs, including web mapping with Mapbox GL JS and mobile mapping with the Maps SDKs for iOS, Android, and Flutter.
Styles can also be used with our server-side map rendering APIs, including Mapbox Static Images API and Mapbox Static Tiles API.
The map below shows the Mapbox Standard style, which is the recommended style for all new projects. It features a clean, modern design with landmark 3D buildings, dynamic lighting, and points of interest. The Standard style is continuously updated and maintained by Mapbox's in-house cartography team to make sure it remains performant, visually appealing, and up-to-date with the latest data.
Pan and zoom the map to explore, use the controls to switch light presets, or search for a location to see how the Standard style renders different types of data across the globe.
To experiment with Mapbox Standard's configuration options, try the Mapbox Standard Style Playground.
Mapbox-maintained styles
Mapbox provides a set of expertly designed map styles that you can use directly in your applications:
- Mapbox Standard — Mapbox's premier vector basemap with realistic 3D buildings, dynamic lighting, featuresets for interactivity, and points of interest. This is the recommended style for all new projects.
- Mapbox Standard Satellite — A variant of Mapbox Standard that uses satellite imagery as its base layer, while retaining the same dynamic lighting and label features.
- Classic Styles — Legacy styles including Light, Dark, Streets, Outdoors, Satellite Streets, and Navigation. These styles are no longer actively maintained. For new projects, use one of the Mapbox Standard styles or create your own custom style.
All Mapbox-maintained styles display Mapbox data, including global vector tilesets like Mapbox Streets, Mapbox Terrain, and Mapbox Bathymetry, and raster tilesets like Mapbox Satellite.
Custom styles
You may use Mapbox-maintained styles as-is, modifying or configuring them in your application code, or you can create your own custom styles using Mapbox Studio. Custom styles allow you to bring in your own data sources, adjust colors and fonts, change layer ordering, and more.
Follow the Create a custom basemap style with Mapbox Studio to learn how to make a custom style.
Mapbox Style URLs
All styles — those maintained by Mapbox and custom styles you create — are referenced by a unique style URL. The format of a style URL is:
mapbox://styles/{username}/{style_id}
Mapbox-maintained styles have a style URL that includes mapbox as the username and a predefined style ID, such as:
mapbox://styles/mapbox/standard
If you make a custom style in Mapbox Studio, it will be assigned a style URL that includes your Mapbox username and the style ID generated during creation, such as:
mapbox://styles/{username}/cmom5qrge002e01s4goc6fjbr
The style URL is shorthand for accessing the style's JSON document via the Styles API. When you reference a style URL in your application, the Mapbox SDK fetches the corresponding style JSON from the Styles API and renders the map.
Use this style URL when initializing a map in any Mapbox SDK or library:
Custom styles you create in Mapbox Studio are also accessible via the Styles API using your Mapbox username and the style ID assigned during creation.
Using Styles in your application
When building interactive web and mobile maps with Mapbox, you have two main approaches to using styles:
Method 1. Initialize the map with a Mapbox-maintained style
Use a Mapbox-maintained style URL directly when initializing your map. This is the fastest way to get started and works well for many common use cases.
When to use this approach:
- Rapid prototyping — get a map on screen quickly without any upfront style design work.
- Overlay features — if you're adding Markers, Annotations, or Popups above the map, you don't need to change the style itself.
- Runtime data — works well when adding sources and layers dynamically at runtime using smaller GeoJSON datasets.
- Style customization in code — with classic styles you can show, hide, or restyle existing layers; with Mapbox Standard you can configure the look and feel to match your app's design using style configuration options.
- Code-first teams — some developers prefer this approach because all map style logic lives in the application codebase alongside other application code.
Tradeoffs:
- You can't use Mapbox Studio's GUI to design or fine-tune the style.
- You must write custom layer styling as JSON style rules in code.
- For cross-platform projects, any runtime style modifications must be replicated independently in each platform's codebase.
Method 2. Create a custom style in Mapbox Studio
Design and publish a custom style using Mapbox Studio, then reference it by its style URL in your application.
When to use this approach:
- Large datasets — import data into Mapbox, create a custom tileset, and incorporate it directly into your style. This is more performant than loading large datasets at runtime.
- Fine-grained design control — Mapbox Studio's visual GUI lets you iterate on colors, fonts, layer ordering, and more without writing code.
- Designer-friendly workflows — designers can go deep on fine-tuning the visual style independently of the engineering team.
- Cross-platform consistency — a single custom style URL can be used across web, iOS, Android, and Flutter apps. Custom data and styling logic lives in the style, not in each platform's codebase, so you only need to keep it in one place.
Tradeoffs:
- Requires upfront work to design and publish a style before you can get started.
- Managing style updates requires coordinating changes in the Style Editor and redeploying if you pin to a specific style version.
Style JSON and the Style Specification
A Mapbox style is a JSON document that tells the map renderer what data to load and how to render it. When you pass a style URL to a Mapbox SDK, the SDK fetches this JSON from the Styles API and uses it to build the map. The Mapbox Style Specification defines every valid property and value.
Most developers will never need to write a full style JSON from scratch — that's what the Style Editor is for. But it's common to work with individual layer objects when adding and styling data at runtime in code.
Style JSON structure
At the top level, a style document contains a few key sections:
{
"version": 8,
"name": "My Style",
"sources": { ... },
"layers": [ ... ],
"imports": [ ... ],
"sprite": "mapbox://sprites/mapbox/standard",
"glyphs": "mapbox://fonts/mapbox/{fontstack}/{range}.pbf"
}
sources— defines where data comes from (vector tilesets, raster tilesets, GeoJSON, etc.)layers— an ordered array of layer objects that define what to draw and how to style itimports— an optional array of other styles to compose into this one (see below)sprite— a URL pointing to icon imagery used for symbol layersglyphs— a URL template for font files used to render text labels
Sources
A source declares a data connection. Here's a GeoJSON source and a vector tileset source:
"sources": {
"my-points": {
"type": "geojson",
"data": "https://example.com/points.geojson"
},
"mapbox-streets": {
"type": "vector",
"url": "mapbox://mapbox.mapbox-streets-v8"
}
}
Layers
Each layer in the layers array references a source and defines how to style that data. Layers are rendered in order from bottom to top. A layer object looks like this:
{
"id": "my-points-layer",
"type": "circle",
"source": "my-points",
"paint": {
"circle-radius": 6,
"circle-color": "#e63946",
"circle-opacity": 0.9
}
}
Common layer types include fill (polygons), line, circle, symbol (icons and labels), and raster. Each type has its own set of paint and layout properties defined in the Style Specification.
Style imports
The Style Specification supports an imports field that lets one style pull in another as a base layer. This makes it possible to build on top of a fully-featured style without copying or maintaining all its layers yourself.
The Mapbox Standard Style is designed to be imported this way. When you create a style in the Style Editor that uses Standard as its base, the resulting style JSON imports Standard rather than duplicating it. This means you automatically receive Mapbox's ongoing updates to the Standard basemap — improved roads, buildings, labels, and lighting — without any action on your part.
{
"version": 8,
"imports": [
{
"id": "basemap",
"url": "mapbox://styles/mapbox/standard"
}
],
"sources": { ... },
"layers": [ ... ]
}
Your custom layers and sources are added on top of the imported style, and you can configure the imported style's exposed options (like light presets or label visibility) without touching its internals. These configuration options also make it possible to customize the style to match the look and feel of your brand or application design.
Adding sources and layers at runtime
Rather than defining everything in a style document upfront, it's common to add sources and layers to a map dynamically after it has loaded. This is useful when your data is fetched at runtime or driven by user interaction.
map.on('load', () => {
// Add a GeoJSON source
map.addSource('my-points', {
type: 'geojson',
data: 'https://example.com/points.geojson'
});
// Add a layer that styles the source
map.addLayer({
id: 'my-points-layer',
type: 'circle',
source: 'my-points',
paint: {
'circle-radius': 6,
'circle-color': '#e63946'
}
});
});
MapboxMap(
onMapLoaded = {
// Add a GeoJSON source
mapboxMap.getStyle { style ->
style.addSource(
geoJsonSource("my-points") {
url("https://example.com/points.geojson")
}
)
// Add a layer that styles the source
style.addLayer(
circleLayer("my-points-layer", "my-points") {
circleRadius(6.0)
circleColor("#e63946")
}
)
}
}
)
Map()
.onMapLoaded { _ in
// Add a GeoJSON source
var source = GeoJSONSource(id: "my-points")
source.data = .url(URL(string: "https://example.com/points.geojson")!)
try? mapboxMap.addSource(source)
// Add a layer that styles the source
var layer = CircleLayer(id: "my-points-layer", source: "my-points")
layer.circleRadius = .constant(6)
layer.circleColor = .constant(StyleColor(UIColor(red: 0.9, green: 0.22, blue: 0.27, alpha: 1)))
try? mapboxMap.addLayer(layer)
}
MapWidget(
onMapCreated: _onMapCreated,
)
Future<void> _onMapCreated(MapboxMap map) async {
// Add a GeoJSON source
await mapboxMap.style.addSource(
GeoJsonSource(
id: "my-points",
data: "https://example.com/points.geojson",
),
);
// Add a layer that styles the source
await mapboxMap.style.addLayer(
CircleLayer(
id: "my-points-layer",
sourceId: "my-points",
circleRadius: 6,
circleColor: 0xe63946,
),
);
});
For a full reference of all source types, layer types, and their properties, see the Mapbox Style Specification. The layer property names differ slightly between platforms (such as camelCase for mobile SDKs vs. kebab-case for GL JS), but the underlying JSON structure and values are the same.