How the map composes

MapState defines a logical map, including its base style and declarative style content. MaplibreMap displays it in Compose UI. Use the state to control the camera, read the visible area, and query features.

The style is base plus content

A MapLibre style is a document with sources and layers. The baseStyle parameter loads that document without modification. The trailing rememberMapState block declares your sources, layers, and their positions in the layer stack.

App.kt

val runtime = DefaultMapRuntime.instance
val state =
  rememberMapState(
    runtime = runtime,
    baseStyle = BaseStyle.Uri("https://tiles.openfreemap.org/styles/liberty"),
  ) {
    // Sources and layers declared here are added to the base style.
  }
MaplibreMap(state = state)

The library manages the sources and layers in the style block. It does not modify the rest of the base style. To change a base style layer, use the asMutable view of its LayerHandle from mapState.style.layers.

Use Compose state to update sources, layers, and images declared in the style block. Use handles for runtime operations such as feature state and cluster queries. For example, mapState.style.sources[source] gives you the typed handle for a declared source. See MapStyleState for handle access and mutation rules.

Recomposition updates the style

The style block is evaluated as a Compose composition. When the state that it reads changes, it recomposes, and the library applies the difference to the style: a layer that is no longer in the composition is removed from the style, a new layer is added, and a changed property is updated in place. You do not call add or remove functions yourself.

This is the same contract as Compose UI: describe the map content for the current state, and let the runtime reconcile it.

Style switches re-apply your content

When you change baseStyle, the map loads the new style and evaluates the style block against it. Each evaluation declares your sources and layers against the new style. They persist across the switch without extra code. An Anchor is resolved against the new style’s layers.

To share one definition between several maps, write the style content as a composable function and call that function from each style block. The same function applies to rememberMapState, MapRuntime.createMapState, and MapRuntime.createSnapshotter.

Use LocalViewport for content that depends on the visible area. When sharing content with a snapshotter, keep interactive behavior separate: LocalMapState is available only in an interactive map.

Layer and source IDs

Layers and sources have string IDs because the underlying MapLibre style identifies them by ID. Within one map, each layer ID must be unique, including against the base style’s layers. A feature query takes layer IDs to limit its scope, and an Anchor can select a base style layer by its ID.