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 bundled style on Android

After Android platform initialization, a style URL can name a file in the APK assets/ directory. asset://style.json and file:///android_asset/style.json both read that file. Prefix the same URL with pmtiles:// for a PMTiles archive in that directory. Add pmtiles to the app’s androidResources.noCompress list so MapLibre can read byte ranges from that archive. Other file:// URLs still read the filesystem, including files the host downloaded into app storage.

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.