Does Leaflet Work in China? Tiles, the Map License & Your Site's ICP
Leaflet itself is open-source front-end code that runs fine in mainland China — but the map tiles it displays come from a separate, offshore provider (OpenStreetMap by default) that can be slow or unreachable in the mainland, and publishing China map data is license- and coordinate-regulated (GCJ-02). A compliance-first look at what it takes to serve a reachable, legal Leaflet map.
Does Leaflet work in China?
Leaflet the library runs fine in mainland China — it is open-source front-end code you bundle, with no personal data of its own. What decides whether a map actually appears, and whether you may publish it, is the tiles Leaflet draws, not Leaflet itself.
Leaflet's own homepage calls it “the leading open-source JavaScript library for building powerful interactive maps,” “weighing just about 42 KB of JS,” and its getting-started example adds a tile layer from OpenStreetMap — tiles fetched from hosts outside the mainland, which from inside China are reached over a long cross-border path and can be slow, patchy, or fail to load. Separately, publishing map data of China is a licensed activity that must use the state-approved GCJ-02 coordinate system, so standard WGS-84 tiles (OpenStreetMap included) sit offset over China and are not licensed for the PRC. The table below separates what Leaflet is from what actually reaches — and is legal — in the mainland.
This is a risk map, not a legal verdict — whether tile reachability, map-data licensing, or your host site's ICP filing is the binding constraint turns on what you build. Our China team can map a reachable, China-legal map path with you →
What Leaflet's own documentation says about China
| Fact | Primary source |
|---|---|
| Leaflet is front-end code you bundle, not a hosted service. Leaflet's own homepage describes it as “the leading open-source JavaScript library for building powerful interactive maps,” “weighing just about 42 KB of JS.” You ship that script from your own origin, so the library itself runs in mainland China like any other JavaScript and holds no personal data of its own — which is exactly why “does Leaflet work in China” is settled by the tiles it draws, not by Leaflet. | Leaflet — leafletjs.com homepage (Overview), retrieved 2026-10-07 |
The map you see comes from a separate tile provider, served offshore. Leaflet draws nothing on its own — you add a tile layer. In Leaflet's own getting-started example that layer is OpenStreetMap: new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', …), whose tiles are fetched from hosts outside mainland China. From inside the mainland those tiles are reached over a long cross-border path, so the map can be slow, patchy, or fail to load even when the Leaflet code itself loaded fine. Reachability is a property of the tile host, not of the library. | Leaflet — leafletjs.com getting-started example (tile layer), retrieved 2026-10-07 |
| Publishing China map data is licensed and coordinate-regulated. Under the Surveying and Mapping Law of the People's Republic of China (2017 revision) and the Map Management Regulations (State Council Order No. 664, in force since 2016), providing internet-map and geolocation services requires a surveying-and-mapping qualification, public maps must use the state-approved coordinate system — the GCJ-02 offset, informally the “Mars” coordinates — and map-data servers must sit inside mainland China. Standard WGS-84 tiles, OpenStreetMap included, are visibly offset over China, and a foreign tile source cannot self-certify it meets these rules. Treat this as a regulatory layer to confirm with counsel, separate from where your site is hosted. | Map Management Regulations, State Council Order No. 664 (gov.cn); Surveying and Mapping Law of the PRC (2017 revision) |
| The site that hosts the map still needs its own ICP filing. Independent of which mapping library you pick, a public-facing website served to mainland visitors from inside China turns on an ICP filing (ICP 备案) under State Council Order No. 292 and MIIT Order No. 33, attached to a mainland hosting resource. Leaflet is only the front end; the filing is about the site it lives on, not the map widget. | State Council Order No. 292 and MIIT Order No. 33 — ICP filing regime (21YunBox explainer) |
Where the data question actually lives: the tile or geocoding backend, not Leaflet. Leaflet itself sends nothing to any server; a visitor's IP, and any location from a map.locate() lookup, only leave the mainland through whatever tile, geocoding or search backend you wire Leaflet to. If that backend is offshore, those calls are a cross-border transfer of personal information under PIPL — notice, separate consent and a transfer mechanism (CAC security assessment, CAC standard contract, or certification), with in-country storage for CIIOs and large-volume handlers (PIPL Chapter III and Article 40). The duty attaches to the provider you choose, so confirm the specifics with counsel. | PIPL Chapter III (Articles 38–43) and Article 40 — read against the tile/geocoding backend's behavior |
Sources verified by the 21YunBox compliance team on 2026-10-07.
For a mainland-China audience, “does Leaflet work in China” splits into two very different questions. Leaflet itself is open-source front-end code you bundle and serve from your own origin, so the library runs in China like any other JavaScript — nothing to block, and none of your users’ personal data inside it. What decides whether a usable map actually appears is everything Leaflet does not ship: the map tiles, which come from a separate provider served offshore, and the map data itself, which China licenses and requires in an approved coordinate system. The code is the easy half; the tiles and the map license are the half that decides it.
Leaflet in China at a glance
| What decides it | What it means for a mainland-China map |
|---|---|
| Leaflet itself | An open-source front-end library (about 42 KB of JS) you bundle and serve from your own origin. It runs in China like any other JavaScript and carries no personal data of its own — so the library is not the thing that "works" or "fails." |
| The map tiles | Come from a separate tile provider — OpenStreetMap by default in Leaflet's own example — served from hosts outside the mainland. Reached over a long cross-border path, so they can be slow, patchy, or fail to load. The map, not the library, is what breaks. |
| Map data & coordinates | Publishing China map data is licensed and must use the state-approved GCJ-02 coordinate system. Standard WGS-84 tiles — OpenStreetMap included — are offset over China and not licensed for the PRC. |
| Serving the public | A public mainland site that embeds the map needs its own ICP filing, independent of which mapping library it uses. |
| The data path | Leaflet sends nothing itself; any IP or location leaving the mainland comes from the tile or geocoding backend you wire it to. That provider's path — not Leaflet — is where PIPL cross-border questions arise. |
The library runs — the tiles are what reach China
Leaflet is not a hosted map service; it is a script. On its own homepage Leaflet is “the leading open-source JavaScript library for building powerful interactive maps,” “weighing just about 42 KB of JS.” You bundle that script and serve it from wherever your site already lives, so inside mainland China the library loads like any other JavaScript. That is why reachability is not really a question about Leaflet.
The map a visitor sees is drawn from tiles, and those tiles are a separate thing you add. In Leaflet’s own getting-started example the layer is OpenStreetMap — new TileLayer('https://tile.openstreetmap.org/{z}/{x}/{y}.png', …) — whose tiles are fetched from hosts outside the mainland. From inside China those requests travel a long cross-border path, so the tiles can arrive slowly, partially, or not at all, and the map comes up blank even though the Leaflet code loaded perfectly. The fix is never “tune Leaflet”; it is to serve the tiles from somewhere the mainland can actually reach. Reaching a map is not the same as being cleared to publish one — which is the next door.
China map data is licensed and coordinate-shifted
Even with fast, reliable tiles, the content of a China map is regulated before performance ever enters it. Under the Surveying and Mapping Law of the People’s Republic of China (2017 revision) and the Map Management Regulations (State Council Order No. 664, in force since 2016), providing internet-map and geolocation services requires a surveying-and-mapping qualification, public maps must use the state-approved coordinate system — the GCJ-02 offset, informally the “Mars” coordinates — and map-data servers must sit inside mainland China.
Two practical consequences follow. First, standard WGS-84 tiles — OpenStreetMap included — are visibly offset over China: roads and markers land tens to hundreds of metres from where they should, because the base data is not in the mandated coordinate frame. Second, a foreign tile source cannot self-certify that it meets these rules, which is why compliant public map data in China is, in practice, served through a qualified, licensed Chinese provider. Whether your specific use needs a licensed China map source is a question to settle with counsel — this is a risk map, not a verdict.
Your public site still needs its own ICP filing
The mapping stack and the hosting licence are separate obligations, and the second one does not go away because you chose an open-source library. A public-facing website served to mainland visitors from inside China turns on an ICP filing (ICP 备案) under State Council Order No. 292 and MIIT Order No. 33, and that filing attaches to a mainland hosting resource. Leaflet is only the front end; the filing is about the site the map lives on. “We already use Leaflet” says nothing about whether the site around it is cleared to operate in the mainland.
Where the data question actually lives
It is worth being precise here, because it is easy to over-claim. Leaflet itself sends no data anywhere — it is browser code. A mainland visitor’s IP address, and any coordinates from a map.locate() lookup, only leave the country through whatever tile, geocoding or search backend you point Leaflet at. If that backend is offshore, those calls become a cross-border transfer of personal information under PIPL: the handler — you, not Leaflet — must give notice, obtain separate consent, and clear a transfer mechanism (a CAC security assessment, the CAC standard contract, or certification), with in-country storage required for critical-information-infrastructure operators and large-volume handlers (PIPL Chapter III and Article 40). The duty tracks the provider you choose, not the library, so it is worth confirming the specifics with counsel as you pick a tile and geocoding source.
Where 21YunBox fits — a compliant overlay, not a migration
You keep your Leaflet front-end exactly as it is — same code, same markers, same interactions. We add the parts an offshore tile source cannot: compliant, ICP-filed delivery from inside the mainland, placed in front of your existing origin so the map and the page actually reach your users, plus help wiring a licensed in-country map source where the rules require one. No rebuild, no second codebase, and no rewrite of your map logic. Our China team maps your tile-reachability, map-data licensing and ICP obligations against your entity and your data, then stands up the in-country delivery a reachable, lawful China map needs — while your Leaflet code stays where it already runs.
Related reading:
