Skip to main content

Set a style

Additional Developer Resources

When adding a map to an Android application using the Maps SDK, you must specify a style to define how the map is displayed. A style dictates the map's visual design, including colors, labels, and feature visibility. It also includes information about data sources, and is used by the SDK to fetch the appropriate data necessary to render the map.

Mapbox has several professionally designed styles for use in various types of applications, and many developers invest in designing highly-customized styles to make their Mapbox maps shine. Explore custom styles in our Style Gallery.

Once a style is loaded, you can continue to manipulate it at runtime, changing the appearance of the map by adding or removing layers, changing layer properties, and more.

This guide explains how to set and configure a style when initializing a map and how to switch styles dynamically during runtime. Developers can choose from a variety of options, including Mapbox Standard, classic Mapbox styles, and custom styles designed in Mapbox Studio.

Load a style​

The Maps SDK provides an embeddable map interface using MapView or MapboxMap. To render a map in the MapView or MapboxMap, you will need to determine which style the renderer should use. You can rely on the Mapbox Standard Style which is loaded by default, or you can specify another style.

Mapbox Standard​

Mapbox Standard is our general-purpose map style that is designed to be used in a wide range of applications, suitable for most use cases and includes a variety of configuration options to customize the map's appearance.

Mapbox Standard is the default style, and instantiating a MapView or MapboxMap without specifying any style means your map will use Mapbox Standard.

// Loads Mapbox Standard Style by default
mapView = MapView(context)

You can explicitly set Mapbox Standard as the style for your map by using the Style.STANDARD constant or calling MapboxStandardStyle() if you are using Jetpack Compose:

mapView = MapView(context, MapInitOptions(
  context = context,
  styleUri = Style.STANDARD
))

Classic styles and custom styles​

Mapbox provides several classic styles, suitable for various use cases. For example, the Mapbox Light and Mapbox Dark styles are designed to be subdued and will allow your custom data to stand out. The Mapbox Outdoors style includes helpful information for outdoor activities, such as hiking trails and contour lines. Mapbox Satellite and Mapbox Satellite Streets provide up-to-date satellite imagery for a closer look at the physical environment.

You can also create your own custom styles using the Mapbox Studio style editor. Custom styles can be used to create a unique look and feel for your map, tailored to your application's design needs and can use Mapbox Standard or a classic style as a base.

You can specify a style to use when you instantiate a map using a Style URL, a Style Constant, or a Style JSON string.

Load a style using a Style URL​

All Mapbox styles and custom styles created in Mapbox Studio have a unique style URL starting with mapbox://. You can use this URL with the styleUri property of MapInitOptions, or using MapStyle with Jetpack Compose.

mapView = MapView(context, MapInitOptions(
  context = context,
  styleUri = "mapbox://styles/mapbox/streets-v12"
))

Load a Mapbox style using a Style Constant​

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

Style NameSDK Constant
Mapbox StandardStyle.STANDARD
Mapbox Standard SatelliteStyle.STANDARD_SATELLITE
Mapbox StreetsStyle.MAPBOX_STREETS
Mapbox LightStyle.LIGHT
Mapbox DarkStyle.DARK
Mapbox OutdoorsStyle.OUTDOORS
Mapbox SatelliteStyle.SATELLITE
Mapbox Satellite StreetsStyle.SATELLITE_STREETS
mapView = MapView(context, MapInitOptions(
  context = context,
  styleUri = Style.OUTDOORS
))
Loading a Style using Style JSON
Though less common, you can also load a style from a JSON string, either loaded from a local file or downloaded over the network. See a minimal style JSON example in Delay setting the style below.

Delay setting the style​

If you want to initialize the MapView but delay loading a style until after the MapView is displayed on the UI, you can set the styleUri to null in MapInitOptions, or pass an empty string to MapStyle when using Jetpack Compose.

// set styleUri to null method
mapview = MapView(context, MapInitOptions(context = context, styleUri = null))

In the case above, MapView is rendered with solid black background color by default. But, if you want to adjust the color of the map's background to fit your design before your style is loaded to the MapView, you can create a minimal style JSON string with a background layer set to the desired color.

@Language("JSON")
    private const val BLANK_STYLE = """
{
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {"background-color": "hsl(100, 50%, 50%)"}
    }
  ]
}
"""

MapView(context, MapInitOptions(context = context, styleUri = BLANK_STYLE))
// or
mapboxMap.loadStyle(BLANK_STYLE)

Set a style in an XML MapView​

If using Android Views, you can add a MapView to the layout with an XML attribute mapbox_styleUri to load a Mapbox-hosted style using a style URL.

<?xml version="1.0" encoding="utf-8"?>
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:mapbox="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent">

    <!-- MapView for displaying the Mapbox map -->
    <com.mapbox.maps.MapView
        android:id="@+id/mapView"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        mapbox:mapbox_styleUri="mapbox://styles/mapbox/streets-v12" />

</RelativeLayout>

Configure a style​

Depending on which map style you choose, you have different configuration options available to customize aspects of your style such as fonts, colors, and more.

Mapbox Standard​

Mapbox Standard and Mapbox Standard Satellite are our default, all-purpose map styles, and are recommended for most use cases. Unlike our classic styles, Mapbox Standard and Mapbox Standard Satellite provide a limited set of configurations instead of allowing for full manipulation of the style.

Each style can be configured with several options, including light presets, label visibility, feature visibility, color theming, and fonts, and more. You can set these at runtime using the setStyleImportConfigProperty method.

All configuration properties for Mapbox Standard are also available for Mapbox Standard Satellite except for toggling 3D objects and color theming. To learn more about configuration options, refer to the Mapbox Standard Guide and the Mapbox Standard API Reference Docs.

The following sample code shows how to change the 3D lights from the default preset, day, to another preset, dusk by setting the lightPreset property. The code also shows how to hide the point of interest labels by setting the showPointOfInterestLabels property to false. The first argument of setStyleImportConfigProperty is the import id, which defaults to "basemap" when using Mapbox Standard.

When using Android Views, these configurations can be applied after the map loads by calling getStyle. When using Jetpack Compose, you can set these configurations before the map loads using the MapboxStandardStyle block.

mapView.mapboxMap.getStyle { style ->
  style.setStyleImportConfigProperty(
    "basemap", // Mapbox Standard's import id is "basemap"
    "lightPreset",
    Value.valueOf("dusk")
  )

  style.setStyleImportConfigProperty(
    "basemap",
    "showPointOfInterestLabels",
    Value.valueOf(false)
  )
}

All configurations are also available in Mapbox Studio, where you can create a custom style that imports Mapbox Standard or Mapbox Standard Satellite and adjust the configurations as needed.

Classic styles and custom styles​

Classic styles and custom styles can be configured by calling methods to update the properties of the style. The most common configurations are updates to layer properties, such as changing the color of a line or the visibility of a label.

For example, you may want to hide an existing layer by setting its visibility to none, or change the color of a fill layer by setting its fill-color property. Learn more about updating layers in the Work with sources and layers guide.

mapView.mapboxMap.getStyle { style ->
  style.setStyleLayerProperty("water", "fill-color", Value.valueOf("#45d9ca"))
}

This approach requires knowing the ids and types of layers in the style and understanding the properties that can be updated for each layer type. You can explore the properties available for a given layer type in the Mapbox Style Specification.

An alternative approach to adding many runtime configuration changes for a classic style is to create a custom style in Mapbox Studio based on the classic style. You can make the desired changes in the style editor and load the custom style in your application.

Change to a different style​

You can change the style any time after initializing the map using the MapboxMap loadStyle method.

mapView.mapboxMap.loadStyle("mapbox://styles/mapbox/dark-v10")

If you added any layers after map initialized, you will need to re-add them after the new style is loaded or try using the new addPersistentLayer when adding any layers to the initial style.

For Jetpack Compose users, you can change the whole MapboxStyleComposable block to switch between customized styles or strongly typed MapboxStandardStyle or MapboxStandardSatelliteStyle. Layers added to slot or layer position of the MapboxStyleComposable will be added as normal layers once the style is loaded and layers added to the MapboxMap content will be added as persistent layer across different styles.

Additional Developer Resources
Was this page helpful?