/maplibre-native-gl-js-parity

name: maplibre-native-gl-js-parity
description: Six places where MapLibre Native (Android, iOS) and MapLibre GL JS differ, release by release — custom URL schemes (`addProtocol`), globe projection, 3D terrain, `interpolate-hcl` and `interpolate-lab`, the `color-relief` layer, and PMTiles — with the Native release that closed each gap, the tracking issue for each still open, and what to do on Native instead. Use when a style or feature that works in the browser does nothing in an Android or iOS app, or when porting MapLibre GL JS code to Kotlin or Swift.
metadata:
  status: verified

MapLibre Native and GL JS Parity

MapLibre GL JS and MapLibre Native read the same style specification but ship features at different times. A style key Native does not know is ignored, and a paint value it cannot parse drops its layer, both without a crash, so the symptom is a map that quietly differs from the browser. The table below names each gap this skill covers, the release that closed it where one has, and what to do on Native instead. Rows were checked against android-v13.7.1 (2026-10-15) and ios-v7.0.0 (2026-10-28).

When to Use This Skill

These are symptoms as you would observe them, before you know the cause:

• **The browser shows a globe, the app stays flat:** the style sets `"projection": {"type": "globe"}` and nothing changes on Android or iOS however far the map zooms out (no Native release draws a globe).
• **One layer never draws on Android or iOS, no crash, every other layer fine:** a paint value uses an expression the installed release does not implement, such as `interpolate-hcl` before android-v13.7.1 or ios-v7.0.0, so the whole layer is dropped.
• **Porting `map.setTerrain(...)` to Kotlin or Swift:** there is nothing to port it to (no Native release has 3D terrain).
• **A `maplibregl.addProtocol` handler needs an Android or iOS equivalent:** there is no `addProtocol` on Native; app code answers the request in each platform's HTTP stack instead.
• **Elevation-banded color on a phone without pre-rendered tiles:** a `color-relief` layer, on Native since android-v13.0.0 and ios-v6.24.0.
• **A `.pmtiles` archive in an iOS or Android app:** no tile server, conversion, or package; `pmtiles://` is built in since android-v11.8.0 and ios-v6.10.0.

**Scope.** The table's six gaps are the ones where a model answering without this skill gets the API or the release wrong. The renderers differ in other places too. For a feature not in the table, find the release that added it in the Native CHANGELOGs.[5] [6] The `js-parity` label tracks open gaps,[1] but some open issues there describe shipped features.

The gaps, and what to do on Native

| Feature | MapLibre GL JS | MapLibre Native | Do on Native | | ---------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | A custom URL scheme for tiles (`vault://…`) | `addProtocol`, promise-based since 4.0.0[9] | No `addProtocol`; [#3562](https://github.com/maplibre/maplibre-native/issues/3562) open[2] | Android: a custom `HttpRequest` from a `ModuleProvider` (android-v11.0.0), an OkHttp interceptor on `https://` URLs the app marks, or a `CustomVectorSource` (android-v13.5.0). iOS: a `URLProtocol` in `MLNNetworkConfiguration`'s `sessionConfiguration` (every release). | | Globe projection (`projection: globe`) | Yes | No release; [#3161](https://github.com/maplibre/maplibre-native/issues/3161) open[3] | Stay on Mercator, or show the globe in a web view running GL JS | | 3D terrain (`map.setTerrain`, the style's `terrain`) | Yes | No release; [#252](https://github.com/maplibre/maplibre-native/issues/252) open[4] | `hillshade` or `color-relief` on the same `raster-dem` source: shading on a flat map, not relief | | `interpolate-hcl`, `interpolate-lab` | Yes | android-v13.7.1, ios-v7.0.0 ([#4668](https://github.com/maplibre/maplibre-native/pull/4668)); earlier releases drop the layer[5] [6] | Upgrade, or keep the release and use a plain `interpolate` ramp with intermediate stops | | `color-relief` layer | 5.6.0[9] | android-v13.0.0,