Your first MapLibre map
Quick answer
This tutorial builds the smallest working map: a container with an explicit height, the maplibre-gl stylesheet and script, a required style URL, and a new maplibregl.Map with center and zoom. It stresses [lng, lat] ordering, adding sources and layers inside the load callback, and the four control positions. You will be able to bootstrap a page and diagnose a blank map.
Key points
- Give #map a real height, because a zero-height parent yields a blank page with no error.
- Pass style at construction, for example the token-free demotiles style, since v4 rejects a missing style.
- Add sources and layers inside map.on('load') and re-add them after any setStyle call.
Example
<!DOCTYPE html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.css">
<style>
html, body { height: 100%; margin: 0; }
#map { height: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script src="https://cdn.jsdelivr.net/npm/maplibre-gl@4/dist/maplibre-gl.js"></script>
<script>
var map = new maplibregl.Map({
container: 'map',
style: 'https://demotiles.maplibre.org/style.json',
center: [116.391263, 39.907359],
zoom: 4
});
map.addControl(new maplibregl.NavigationControl(), 'top-right');
</script>
</body>
</html>map.on('load', function () {
map.addSource('points', {
type: 'geojson',
data: { type: 'Point', coordinates: [116.39, 39.90] }
});
map.addLayer({
id: 'points',
type: 'circle',
source: 'points',
paint: { 'circle-radius': 6, 'circle-color': '#1f5fd0' }
});
});
Notes
- Using Mapbox style URLs with access tokens returns 401 and only shows failed tile requests.
- Zooming past level 6 on demotiles overzooms stretched tiles, which looks like a rendering bug.
English edition written for Atlaslog. Code is taken from the original Chinese page and runs unchanged.
Atlaslog (2026). Your first MapLibre map. https://www.jingweizhi.com/en/maplibre/tutorials/minimal-scene.html (accessed 2026-11-03).