MapLibre GL JS — Open-Source WebGL Map Rendering Library

Introduction

MapLibre GL JS is a community-led fork of Mapbox GL JS v1 created after Mapbox changed its license to proprietary. It renders vector tile maps in the browser using WebGL, giving developers a fully open-source mapping library with no usage fees or API key requirements for the rendering engine itself.

What MapLibre GL JS Does

• Renders vector and raster tile maps in the browser at 60 fps using WebGL
• Supports the Mapbox Style Specification for defining map layers, colors, and typography
• Provides camera controls including pitch, bearing, zoom, and fly-to animations
• Handles GeoJSON, vector tiles (MVT), raster tiles, and terrain data sources
• Offers a plugin API for custom layers, controls, and data sources

Architecture Overview

MapLibre GL JS parses a JSON style document that references tile sources and defines rendering rules. It fetches vector tiles over HTTP, decodes the protobuf payloads, and tessellates geometry into WebGL buffers. A render loop driven by requestAnimationFrame composites layers in z-order. Web workers handle tile parsing off the main thread to keep interactions smooth. The library exposes an event system for map clicks, moves, and data loading.

Self-Hosting & Configuration

• Install from npm or load from a CDN with no API key required
• Provide a style JSON URL pointing to your tile server (e.g., OpenMapTiles, Protomaps, or Maptiler)
• Self-host tiles with tileserver-gl, Martin, or PMTiles for fully offline maps
• Configure sources, layers, and expressions in the style document
• Use the addControl API to add navigation, scale bars, geolocation, and custom UI

Key Features

• Fully open-source under the BSD-3-Clause license with no usage-based pricing
• 3D terrain rendering with hillshade and sky layers
• Right-to-left text support for Arabic and Hebrew scripts
• Globe projection for world views alongside Mercator for detail
• Compatible with existing Mapbox GL JS plugins and styles with minimal changes

Comparison with Similar Tools

• Mapbox GL JS v2+ — Proprietary license with usage fees; MapLibre is the free open-source continuation of v1
• Leaflet — Lightweight 2D map library using DOM elements; MapLibre uses WebGL for smooth vector rendering and 3D
• OpenLayers — Full-featured mapping library; MapLibre focuses on vector tile rendering with a simpler API
• deck.gl — Uber's large-scale data visualization layer; often used on top of MapLibre as the base map

FAQ

Q: Is MapLibre GL JS a direct fork of Mapbox GL JS? A: Yes. It forked from Mapbox GL JS v1.13 (the last open-source version) and has been independently maintained and improved since then.

Q: Do I need an API key? A: No. The rendering library itself is free. You only need keys if your tile provider requires them.

Q: Can I use it with React or Vue? A: Yes. Libraries like react-map-gl and vue-maplibre-gl provide framework bindings on top of MapLibre GL JS.

Q: Does it support offline maps? A: Yes. Serve tiles locally from a file (PMTiles) or a local tile server and the map works without internet access.

Sources

• https://github.com/maplibre/maplibre-gl-js
• https://maplibre.org/maplibre-gl-js/docs/