Introduction - MapLibre GL JS

Skip to content

CSP Directives

MapLibre CSS

Plugins

Style Specifications

API

Enumerations

Functions

Interfaces

Type aliases

Variables

Examples

Guides

CSP Directives

MapLibre CSS

Introduction

MapLibre GL JS is a TypeScript library that uses WebGL to render interactive maps from vector tiles in a browser.<br>The map’s appearance is controlled by a style document whose structure and properties are defined by the MapLibre Style Spec.<br>It is part of the MapLibre ecosystem, with a counterpart for Android, iOS and other platforms called MapLibre Native.

Quickstart

link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^6.1.0/dist/maplibre-gl.css" /><br>div id="map" style="height: 400px">div><br>script type="module"><br>import * as maplibregl from 'https://unpkg.com/maplibre-gl@^6.1.0/dist/maplibre-gl.mjs';

const map = new maplibregl.Map({<br>container: 'map', // container id<br>style: 'https://demotiles.maplibre.org/globe.json', // style URL<br>center: [0, 0], // starting position [lng, lat]<br>zoom: 2 // starting zoom<br>});<br>script>

Reading this documentation

This documentation is divided into several sections:

Main - The Main section holds the following classes<br>Map object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.

Global Functions let you set global properties and options that you might want to access while initializing your map or accessing information about its status.

Markers and Controls - This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's canvas element. This consists of Marker, Popup and all the controls.

Geography and geometry - This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.

User interaction handlers - The items in this section relate to the ways in which the map responds to user input.

Sources - This section describes the source types MapLibre GL JS can handle besides the ones described in the MapLibre Style Specification.

Event Related - This section describes the different types of events that MapLibre GL JS can raise.

Each section describes classes or objects as well as their properties , parameters , instance members , and associated events . Many sections also include inline code examples and related resources.

In the examples, we use vector tiles from our Demo tiles repository and from MapTiler. Get your own API key if you want to use MapTiler data in your project.

npm

Install the MapLibre GL JS package via npm.

npm install maplibre-gl

You can then import the MapLibre GL JS module in your project.

div id="map">div>

import {Map} from 'maplibre-gl';<br>import 'maplibre-gl/dist/maplibre-gl.css';

const map = new Map({<br>container: 'map', // container id<br>style: 'https://demotiles.maplibre.org/globe.json', // style URL<br>center: [0, 0], // starting position [lng, lat]<br>zoom: 1 // starting zoom<br>});

See the ESM section below for setting up the worker URL with your bundler.

ESM

MapLibre GL JS v6 ships as ES modules only (maplibre-gl.mjs). The "module" field in package.json points at the ESM bundle, so bundlers pick it up automatically.

For minimal runnable apps per bundler (Vite, webpack, esbuild, Rollup), see test/integration/bundler/.

Upgrading from v5? See the v5 to v6 migration guide.

Installation

Pick your setup:

Vitewebpack 5+esbuildRollupCDN / No bundler

Use Vite's ?worker&url query to get a bundled, self-contained worker URL:

import {Map, setWorkerUrl} from 'maplibre-gl';<br>import 'maplibre-gl/dist/maplibre-gl.css';<br>import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';

setWorkerUrl(workerUrl);

const map = new Map({/* … */});

Use ?worker&url rather than plain ?url: the dist worker imports its<br>sibling maplibre-gl-shared.mjs, and ?url emits the worker file verbatim<br>in production builds without that sibling — the worker then fails on its<br>first import and no vector tiles load. ?worker&url routes the file<br>through Vite's worker pipeline, emitting a self-contained chunk. Dev mode<br>works with either.

If your build uses SSR (TanStack Start, Astro, etc.) and Vite resolves the CommonJS entry on the server, also add:

// vite.config.ts<br>export default defineConfig({<br>ssr: {noExternal: ['maplibre-gl']}<br>});

import {Map, setWorkerUrl} from 'maplibre-gl';<br>import 'maplibre-gl/dist/maplibre-gl.css';

setWorkerUrl(new URL('maplibre-gl/dist/maplibre-gl-worker.mjs', import.meta.url).toString());

const map = new Map({/* … */});

rspack and rsbuild use the same pattern.

// build.js<br>import * as esbuild from 'esbuild';<br>import {copyFileSync} from 'fs';

await esbuild.build({<br>entryPoints: ['src/main.ts'],<br>bundle: true,<br>outdir: 'dist',<br>format:...