Source: https://maps.vietmap.vn/docs/map-api/tilemap-leaflet/

# Leaflet Integration

For an existing Leaflet project, the [`@vietmap/vietmap-gl-leaflet`](https://www.npmjs.com/package/@vietmap/vietmap-gl-leaflet) package adds VIETMAP GL JS to the map as a layer — you keep the Leaflet API and every plugin you already use, while WebGL renders the vector base map. It is a port of [maplibre-gl-leaflet](https://github.com/maplibre/maplibre-gl-leaflet).

The include order is mandatory: Leaflet → VIETMAP GL JS → plugin.

```html
<link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.3/dist/leaflet.css" />
<link rel="stylesheet" href="https://unpkg.com/@vietmap/vietmap-gl-js/dist/vietmap-gl.css" />

<div id="map" style="height: 400px"></div>

<script src="https://unpkg.com/leaflet@1.9.3/dist/leaflet.js"></script>
<script src="https://unpkg.com/@vietmap/vietmap-gl-js/dist/vietmap-gl.js"></script>
<script src="https://unpkg.com/@vietmap/vietmap-gl-leaflet/leaflet-vietmap-gl.js"></script>

<script>
  var VIETMAP_API_KEY = '{your-apikey}';

  var map = L.map('map', {
    maxBounds: [[180, -Infinity], [-180, Infinity]], // GL JS clamps latitude harder than Leaflet
    maxBoundsViscosity: 1,                           // make those bounds solid
    minZoom: 1                                       // avoid sync issues at zoom 0
  }).setView([10.762622, 106.660172], 13);

  var gl = L.vietmapGL({
    style: 'https://maps.vietmap.vn/maps/styles/tm/style.json?apikey=' + VIETMAP_API_KEY
  }).addTo(map);

  L.marker([10.762622, 106.660172])
    .bindPopup('Hello <b>Leaflet GL</b>!')
    .addTo(map)
    .openPopup();
</script>
```

Swap `tm` in the style URL for `lm`, `dm` or `hm` to use another style — see the [vector styles table](https://maps.vietmap.vn/docs/map-api/tilemap/#vietmap-maps-sdk-integration). A map you built in [Map Editor](https://maps.vietmap.vn/docs/map-api/map-editor/) works here too: paste its style link into `style`.

If you use a bundler, install from npm together with its peer dependencies:

```bash
npm install leaflet @vietmap/vietmap-gl-js @vietmap/vietmap-gl-leaflet
```

**Layer options**

|Option|Default|Description|
|--- |--- |--- |
|`style`|none|`style.json` URL of the base map, including your `apikey`.|
|`pane`|`tilePane`|Leaflet pane the GL layer is drawn into. It sits below markers and popups, so your Leaflet layers always stay on top of the base map.|
|`padding`|`0.1`|How far the rendered area extends beyond the viewport — `0.1` is 10% on each side.|
|`interactive`|`false`|Whether mouse and keyboard events are bound to the GL layer.|
|`updateInterval`|`32`|Interval in ms between syncs while panning.|

`gl.getVietmapMap()` returns the VIETMAP GL JS `Map` object, so you can call GL JS APIs on it — for example to add the [traffic layer](https://maps.vietmap.vn/docs/map-api/traffic-layer/). Wait for the `load` event before adding sources and layers:

```js
var vietmapMap = gl.getVietmapMap();

vietmapMap.on('load', function () {
  vietmapMap.addSource('traffic', { /* sources from tf/style.json */ });
  vietmapMap.addLayer({ /* layer from tf/style.json */ });
});
```

!!! note "Do not disable Leaflet's attribution"
    The plugin turns off the GL map's own attribution control, reads attribution from the style, and hands it to Leaflet's attribution control instead. So do not set `attributionControl: false` on the Leaflet map — that would drop attribution entirely.

!!! warning "Trade-offs of the binding"
    - **No map rotation** — no bearing, no pitch.
    - **Slower than GL JS on its own.** The GL layer runs non-interactive; Leaflet receives the mouse and touch events and updates the GL map behind it, and GL JS redraws more slowly than Leaflet.
    - **Keep `maxBounds`, `maxBoundsViscosity` and `minZoom: 1`** from the example: GL JS clamps maximum latitude harder than Leaflet, and zoom level 0 makes the two maps drift apart.

    In return you get every Leaflet plugin. If you do not need any of them, using the [Web SDK](https://maps.vietmap.vn/docs/sdk-web-gl/overview/) directly is faster and more capable.

If you only need satellite imagery, you do not need the plugin — use `L.tileLayer` with the URL from the [raster tiles table](https://maps.vietmap.vn/docs/map-api/tilemap/#vietmap-maps-sdk-integration).