Load a style

A style defines the tiles, layers, and drawing order of a map. Load one before rendering a new map.

Choose where the style comes from

Set a style URL for a hosted base map. MapLibre fetches it through the resource system that also loads tiles. The request therefore uses the runtime’s cache, offline regions, and resource transform.

load-style.c

// Returns once the map accepts the request. The style, its sources, and its
// tiles arrive across the pumps that follow.
return mln_map_set_style_url(map, style_url);

Set style text when the host already has the document, such as a bundled base style or one composed at runtime. MapLibre parses and copies the text before the call returns.

load-style.c

// MapLibre parses or copies these UTF-8 bytes before the call returns.
const mln_buffer_view json = {.data = style_json, .size = strlen(style_json)};
return mln_map_set_style_json(map, json);

Either call returns when the map accepts the request. Later pumps load the style, sources, glyphs, and first tiles. A style-loaded event reports that the style has parsed and its sources exist. A loading-failed event carries the failure text. Handle events covers reading both.

Load a local style

Use a file:// URL for an explicit file path. Use asset://style.json to load style.json from the runtime’s asset path, which you can set to any directory.

On Android, the asset path defaults to /android_asset. After platform initialization, both asset://style.json and file:///android_asset/style.json read APK assets/style.json.

For APK-bundled PMTiles sources, use pmtiles://asset://map.pmtiles. Add pmtiles to the app’s androidResources.noCompress list for byte-range reads.

Replay additions after a style load

Sources, layers, images, and layer properties that your host adds belong to the style that was loaded when they were added. Loading another style discards all of them.

A host adds its own data after the style-loaded event and repeats those changes after every later style load. A host that switches base maps keeps the changes that it needs to replay.

Camera state survives a style load unchanged.