Style the map

A style is a JSON document that tells the map what to draw. It lists the data sources, such as vector tiles, and the layers that draw that data: roads, water, buildings, labels.

Choose a style

You usually get a style from a map tile provider, which serves the style and the tiles it uses. The awesome-maplibre list names free and commercial providers. The examples in this documentation use OpenFreeMap, which needs no account, and Protomaps, which needs an API key.

To design your own style, edit one in Maputnik, a visual style editor.

Use a style

Pass the style’s URL as a BaseStyle.Uri to rememberMapState, then pass the state to MaplibreMap:

App.kt

val simple =
  rememberMapState(baseStyle = BaseStyle.Uri("https://tiles.openfreemap.org/styles/liberty"))
MaplibreMap(state = simple)

Without a baseStyle, the map uses BaseStyle.Demo, a simple world map from MapLibre’s demo tiles.

Switch styles at runtime

When the baseStyle argument changes, the map loads the new style. This example follows the system theme and shows a dark map in dark mode:

App.kt

val flavor = if (isSystemInDarkTheme()) "dark" else "light"
val themed =
  rememberMapState(
    baseStyle =
      BaseStyle.Uri("https://api.protomaps.com/styles/v5/$flavor/en.json?key=MY_API_KEY")
  )
MaplibreMap(state = themed)

The sources and layers you declare in the rememberMapState block stay on the map when the style changes. Add data to the map shows how to declare them, and How the map composes explains what a style change resets.

Ship a style with your app

Put the style file under your module’s composeResources/files/ folder and pass its URI from Compose Multiplatform resources:

App.kt

val local = rememberMapState(baseStyle = BaseStyle.Uri(Res.getUri("files/styles/colorful.json")))
MaplibreMap(state = local)

A packaged style can still load tiles, fonts, and icons from the network. To show maps without a network connection, see Download maps for offline use.

To build a style in code instead, pass its JSON to BaseStyle.Json.