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 the Maps SDK, you will set the style of the map after initializing the map view.

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. For example, for a store finder application you probably want to use a style with a high density of points of interest (POI) labels like Mapbox Streets. For an application visualizing census data, you should consider a style like Mapbox Light with fewer features to avoid cluttering the data.

Mapbox offers several cartographer-designed styles that are ready to be loaded into any application. Read more about these map styles on the Maps page.

If the Mapbox-designed styles don’t meet your needs, you can also create a custom map style using Mapbox Studio and load it into your application. Read more about custom map styles in the Mapbox Studio Manual.

guide
Getting started: Map styles

Learn how Mapbox styles work and where you can go to learn more and get started designing your map.

Load a style

The Maps SDK’s MapView provides an embeddable map interface. You can embed the map inside a view, allow users to manipulate it with standard gestures, and more. In order for a map to appear in the MapView, the renderer needs a style to determine how to render the map on the screen.

Default style

If you don’t specify a style when initializing a map, the Maps SDK will use the Mapbox Streets style by default.

You can load the style when you first initialize the map view by specifying the style in MapInitOptions and passing the options to MapView. Alternately, you can set the style at any time after the map has been initialized using one of MapboxMap’s loadStyle methods.

You can define the default style while adding the MapView to the layout using XML or you can load a style separately from initializing the map using MapboxMap’s loadStyleUri to load a Mapbox-hosted style using a style URL.

mapboxMap = binding.mapView.getMapboxMap()
// Where STYLE_URL is a string
mapboxMap.loadStyleUri(STYLE_URL)

If you are using a Mapbox-designed style, you can use these convenience variables instead of the full style URL. This will also ensure you’re using the latest version of the style:

  • Mapbox Streets: Style.MAPBOX_STREETS
  • Mapbox Outdoors: Style.OUTDOORS
  • Mapbox Satellite: Style.SATELLITE
  • Mapbox Satellite Streets: Style.SATELLITE_STREETS
  • Mapbox Light: Style.LIGHT
  • Mapbox Dark: Style.DARK
  • Mapbox Traffic Day: Style.TRAFFIC_DAY
  • Mapbox Traffic Night: Style.TRAFFIC_NIGHT
Use loadStyleJson

Though less common, you can also use MapboxMap’s loadStyleJson to load a style if you've written style JSON manually.

Switch styles at runtime

You can also change the style any time after initializing the map using any of loadStyle methods described above. If you added any layers at runtime, you will need to re-add layers after the new style is loaded or try using the new addPersistentLayer (this is an experimental API and is a subject to change) when adding any layers to the initial style.