Integration

Lazy loading

A map embedded far down a CMS article should not make the whole page slower. Until someone scrolls near it, this page has downloaded 20 KB of map0 and nothing else — no MapLibre, no config, no tiles.

Try it

Open the network panel of your developer tools, reload this page, and look at what arrives: map0.js and one chunk. Then scroll down. As the map approaches the viewport, the engine, MapLibre, its stylesheet, the config and finally the tiles are fetched.

↓ keep scrolling an article, a form, whatever your page has above the map

Loaded on demand: the observer starts loading 300 px before the element enters the viewport, so in normal scrolling the map is usually ready by the time you see it.

What it costs, and when

Page load	~20 KB gz — the custom element and Lit
Map in view	+ ~314 KB gz — engine, MapLibre, its stylesheet
On demand	capabilities parsing, proj4, PMTiles and the dialogs, per feature used

A page with three maps below the fold pays the 20 KB once, and the rest only for the maps a reader actually reaches — MapLibre itself is shared between them.

Controlling it

Lazy is the default. The attribute mirrors <img loading>, and it lives on the element rather than in the JSON config for a simple reason: it decides whether the config is fetched at all.

          <!-- default: waits until it is nearly in view -->
          <map0-viewer config-src="/configs/map.json"></map0-viewer>

          <!-- above the fold, or a screenshot service: start immediately -->
          <map0-viewer config-src="/configs/map.json" loading="eager"></map0-viewer>

Elements inside a hidden tab or accordion never intersect, so they stay unloaded until shown — which also avoids MapLibre initialising into a zero-size container. If you need to force it, call load():

          document.querySelector('map0-viewer').load();