Maplibre GL JS Expert

Expert guidance for Maplibre GL JS - a powerful, open-source TypeScript library that uses WebGL to render interactive maps from vector tiles.

When to Use This Skill

Use this skill when users ask about:

• Setup & Installation: Installing Maplibre GL JS, basic map initialization, framework integration
• Map Configuration: Map options, camera controls, bounds, projections
• Styling: Map styles, style specification, themes, custom styling
• Layers: Adding/removing layers, layer types (fill, line, symbol, circle, heatmap, etc.)
• Sources: Vector tiles, GeoJSON, raster sources, real-time data
• Markers & Popups: Adding markers, custom markers, popups, tooltips
• Interactivity: Click events, hover effects, feature queries, user interactions
• Controls: Zoom, navigation, scale, geolocate, custom controls
• Data Visualization: Heatmaps, clustering, 3D extrusions, data-driven styling
• Performance: Optimization, large datasets, vector tiles
• Integration: React, Vue, Angular, TypeScript usage

Core Concepts

What is Maplibre GL JS?

Maplibre GL JS is an open-source TypeScript library that:

• ✅ Renders interactive maps using WebGL
• ✅ Uses vector tiles for efficient, scalable maps
• ✅ Supports custom styling via MapLibre Style Spec
• ✅ Provides smooth animations and camera transitions
• ✅ Works on web, mobile, and desktop platforms
• ✅ Fork of Mapbox GL JS (v1.x), fully community-driven

Key Features

• Vector Tiles: Efficient, scalable map rendering
• WebGL Rendering: Hardware-accelerated graphics
• Style Specification: JSON-based styling system
• Interactive: Click, hover, drag, and touch events
• Data-Driven: Style based on feature properties
• 3D Support: Terrain, buildings, custom 3D models
• Open Source: MIT licensed, no API keys required

Installation

Using npm/bun

# Install with bun
bun add maplibre-gl

# Or with npm
npm install maplibre-gl

TypeScript Types are included by default - no separate @types/maplibre-gl package needed.

CSS Import (with Bundlers)

import "maplibre-gl/dist/maplibre-gl.css";

Using CDN

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Maplibre GL JS</title>
    <meta name="viewport" content="width=device-width, initial-scale=1" />

    <!-- Maplibre GL JS CSS -->
    <link
      href="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.css"
      rel="stylesheet"
    />

    <!-- Maplibre GL JS -->
    <script src="https://unpkg.com/maplibre-gl@latest/dist/maplibre-gl.js"></script>

    <style>
      body {
        margin: 0;
        padding: 0;
      }
      #map {
        position: absolute;
        top: 0;
        bottom: 0;
        width: 100%;
      }
    </style>
  </head>
  <body>
    <div id="map"></div>

    <script>
      const map = new maplibregl.Map({
        container: "map",
        style: "https://demotiles.maplibre.org/style.json",
        center: [0, 0],
        zoom: 1,
      });
    </script>
  </body>
</html>

Content Security Policy (CSP)

If you're using CSP, you may need to add the following directives for MapLibre GL JS:

Content-Security-Policy: script-src 'self' 'unsafe-eval' 'unsafe-inline' blob: data:; worker-src 'self' blob: data:; connect-src 'self' blob: data:; img-src 'self' blob: data:; font-src 'self' blob: data:; style-src 'self' 'unsafe-inline';

Quick Start

Basic Map Setup

import maplibregl from "maplibre-gl";
import "maplibre-gl/dist/maplibre-gl.css";

const map = new maplibregl.Map({
  container: "map", // div id
  style: "https://demotiles.maplibre.org/style.json", // map style
  center: [-74.5, 40], // starting position [lng, lat]
  zoom: 9, // starting zoom
});

Map Container

HTML:

<div id="map" style="width: 100%; height: 500px;"></div>

Important: The map container must have a defined width and height.

Map Options

const map = new maplibregl.Map({
  container: "map",
  style: "https://demotiles.maplibre.org/style.json",

  // Initial view
  center: [lng, lat],
  zoom: 12,
  bearing: 0, // rotation (0-360)
  pitch: 0, // tilt (0-60)

  // Bounds (alternative to center/zoom)
  // bounds: [[-74.5, 40], [-73.5, 41]],

  // Interaction
  interactive: true,
  dragPan: true,
  dragRotate: true,
  scrollZoom: true,
  doubleClickZoom: true,
  touchZoomRotate: true,
  touchPitch: true,
  keyboard: true,

  // Limits
  minZoom: 0,
  maxZoom: 22,
  minPitch: 0,
  maxPitch: 60,
  maxBounds: [
    [-180, -90],
    [180, 90],
  ], // restrict panning

  // Performance
  preserveDrawingBuffer: false,
  antialias: false,

  // Hash in URL
  hash: false, // set to true for #map=zoom/lat/lng

  // Terrain
  terrain: {
    source: "terrain-source",
    exaggeration: 1.5,
  },
});

Working with Styles

Using Pre-made Styles

// Maplibre demo tiles (free)
const map = new maplibregl.Map({
  style: "https://demotiles.maplibre.org/style.json",
});

// Custom style URL
const map = new maplibregl.Map({
  style: "https://api.maptiler.com/maps/streets/style.json?key=YOUR_KEY",
});

Inline Style Object

const map = new maplibregl.Map({
  container: "map",
  style: {
    version: 8,
    sources: {
      "osm-tiles": {
        type: "raster",
        tiles: [
          "https://a.tile.openstreetmap.org/{z}/{x}/{y}.png",
          "https://b.tile.openstreetmap.org/{z}/{x}/{y}.png",
          "https://c.tile.openstreetmap.org/{z}/{x}/{y}.png",
        ],
        tileSize: 256,
        attribution: "© OpenStreetMap contributors",
      },
    },
    layers: [
      {
        id: "osm-layer",
        type: "raster",
        source: "osm-tiles",
      },
    ],
  },
  center: [0, 0],
  zoom: 2,
});

Changing Style Dynamically

// Load new style
map.setStyle("https://demotiles.maplibre.org/style.json");

// Wait for style to load
map.on("style.load", () => {
  console.log("Style loaded");
});

Camera Controls

Jump (Instant)

map.jumpTo({
  center: [-74.5, 40],
  zoom: 12,
  bearing: 45,
  pitch: 30,
});

Ease (Animated)

map.easeTo({
  center: [-74.5, 40],
  zoom: 12,
  duration: 2000, // milliseconds
  easing: (t) => t, // linear easing
});

Fly (Curved Path)

map.flyTo({
  center: [-74.5, 40],
  zoom: 12,
  speed: 1.2, // animation speed
  curve: 1, // curve intensity
  essential: true, // animation runs even if prefers-reduced-motion
});

Fit Bounds

// Fit map to bounding box
map.fitBounds(
  [
    [-74.5, 40], // southwest
    [-73.5, 41], // northeast
  ],
  {
    padding: 20, // pixels
    maxZoom: 15,
    duration: 1000,
  }
);

Get Current Camera

const center = map.getCenter(); // LngLat object
const zoom = map.getZoom();
const bearing = map.getBearing();
const pitch = map.getPitch();

console.log(`Center: ${center.lng}, ${center.lat}`);
console.log(`Zoom: ${zoom}`);

Adding Markers

Basic Marker

import maplibregl from "maplibre-gl";

const marker = new maplibregl.Marker().setLngLat([-74.5, 40]).addTo(map);

Custom Color

const marker = new maplibregl.Marker({ color: "#FF0000" })
  .setLngLat([-74.5, 40])
  .addTo(map);

Custom HTML Marker

// Create custom element
const el = document.createElement("div");
el.className = "custom-marker";
el.style.backgroundImage = "url(/marker-icon.png)";
el.style.width = "32px";
el.style.height = "32px";
el.style.backgroundSize = "100%";

const marker = new maplibregl.Marker({ element: el })
  .setLngLat([-74.5, 40])
  .addTo(map);

Draggable Marker

const marker = new maplibregl.Marker({ draggable: true })
  .setLngLat([-74.5, 40])
  .addTo(map);

// Listen to drag events
marker.on("dragend", () => {
  const lngLat = marker.getLngLat();
  console.log(`Marker moved to: ${lngLat.lng}, ${lngLat.lat}`);
});

Marker with Popup

const popup = new maplibregl.Popup({ offset: 25 }).setHTML(
  "<h3>Location Name</h3><p>Description here</p>"
);

const marker = new maplibregl.Marker()
  .setLngLat([-74.5, 40])
  .setPopup(popup)
  .addTo(map);

Remove Marker

marker.remove();

Working with Popups

Basic Popup

const popup = new maplibregl.Popup()
  .setLngLat([-74.5, 40])
  .setHTML("<h3>Hello World!</h3>")
  .addTo(map);

Popup Options

const popup = new maplibregl.Popup({
  closeButton: true,
  closeOnClick: true,
  closeOnMove: false,
  anchor: "bottom", // 'top', 'bottom', 'left', 'right'
  offset: 25, // pixels
  className: "custom-popup",
  maxWidth: "300px",
})
  .setLngLat([-74.5, 40])
  .setHTML("<h3>Popup Content</h3>")
  .addTo(map);

Popup on Click

map.on("click", "poi-layer", (e) => {
  const coordinates = e.features[0].geometry.coordinates.slice();
  const description = e.features[0].properties.description;

  new maplibregl.Popup().setLngLat(coordinates).setHTML(description).addTo(map);
});

// Change cursor on hover
map.on("mouseenter", "poi-layer", () => {
  map.getCanvas().style.cursor = "pointer";
});

map.on("mouseleave", "poi-layer", () => {
  map.getCanvas().style.cursor = "";
});

Adding Sources and Layers

GeoJSON Source

map.on("load", () => {
  // Add source
  map.addSource("points", {
    type: "geojson",
    data: {
      type: "FeatureCollection",
      features: [
        {
          type: "Feature",
          geometry: {
            type: "Point",
            coordinates: [-74.5, 40],
          },
          properties: {
            title: "Location 1",
            description: "Description here",
          },
        },
      ],
    },
  });

  // Add layer
  map.addLayer({
    id: "points-layer",
    type: "circle",
    source: "points",
    paint: {
      "circle-radius": 8,
      "circle-color": "#FF0000",
      "circle-stroke-width": 2,
      "circle-stroke-color": "#FFFFFF",
    },
  });
});

Vector Tile Source

map.addSource("vector-tiles", {
  type: "vector",
  tiles: ["https://example.com/tiles/{z}/{x}/{y}.pbf"],
  minzoom: 0,
  maxzoom: 14,
});

map.addLayer({
  id: "buildings",
  type: "fill-extrusion",
  source: "vector-tiles",
  "source-layer": "building", // layer name in vector tile
  paint: {
    "fill-extrusion-color": "#aaa",
    "fill-extrusion-height": ["get", "height"],
    "fill-extrusion-base": ["get", "min_height"],
    "fill-extrusion-opacity": 0.6,
  },
});

MapLibre Tiles (MLT) Encoding

MapLibre GL JS supports MapLibre Tiles (MLT) encoding for vector sources:

map.addSource("vector-tiles-mlt", {
  type: "vector",
  tiles: ["https://example.com/tiles/{z}/{x}/{y}.mlt"],
  encoding: "mlt", // Use MLT encoding
  minzoom: 0,
  maxzoom: 14,
});

map.addLayer({
  id: "buildings-mlt",
  type: "fill-extrusion",
  source: "vector-tiles-mlt",
  "source-layer": "building",
  paint: {
    "fill-extrusion-color": "#aaa",
    "fill-extrusion-height": ["get", "height"],
    "fill-extrusion-base": ["get", "min_height"],
    "fill-extrusion-opacity": 0.6,
  },
});

Raster Source

map.addSource("satellite", {
  type: "raster",
  tiles: ["https://a.tile.openstreetmap.org/{z}/{x}/{y}.png"],
  tileSize: 256,
});

map.addLayer({
  id: "satellite-layer",
  type: "raster",
  source: "satellite",
  paint: {
    "raster-opacity": 0.8,
  },
});

Update GeoJSON Source

const source = map.getSource("points");
if (source && source.type === "geojson") {
  source.setData({
    type: "FeatureCollection",
    features: newFeatures,
  });
}

Layer Types

Circle Layer

map.addLayer({
  id: "circles",
  type: "circle",
  source: "points",
  paint: {
    "circle-radius": 10,
    "circle-color": "#007cbf",
    "circle-opacity": 0.8,
    "circle-stroke-width": 2,
    "circle-stroke-color": "#fff",
  },
});

Symbol Layer (Icons/Text)

// First, load the image
map.loadImage("/marker-icon.png", (error, image) => {
  if (error) throw error;
  map.addImage("custom-marker", image);

  // Then add the layer
  map.addLayer({
    id: "symbols",
    type: "symbol",
    source: "points",
    layout: {
      "icon-image": "custom-marker",
      "icon-size": 1,
      "icon-allow-overlap": true,
      "text-field": ["get", "title"],
      "text-font": ["Open Sans Semibold"],
      "text-offset": [0, 1.5],
      "text-anchor": "top",
    },
    paint: {
      "text-color": "#000",
      "text-halo-color": "#fff",
      "text-halo-width": 2,
    },
  });
});

Line Layer

map.addLayer({
  id: "route",
  type: "line",
  source: "route-source",
  layout: {
    "line-join": "round",
    "line-cap": "round",
  },
  paint: {
    "line-color": "#888",
    "line-width": 8,
    "line-opacity": 0.8,
  },
});

Fill Layer

map.addLayer({
  id: "polygon",
  type: "fill",
  source: "polygon-source",
  paint: {
    "fill-color": "#088",
    "fill-opacity": 0.4,
    "fill-outline-color": "#000",
  },
});

Heatmap Layer

map.addLayer({
  id: "heatmap",
  type: "heatmap",
  source: "earthquakes",
  paint: {
    "heatmap-weight": [
      "interpolate",
      ["linear"],
      ["get", "magnitude"],
      0,
      0,
      6,
      1,
    ],
    "heatmap-intensity": ["interpolate", ["linear"], ["zoom"], 0, 1, 9, 3],
    "heatmap-color": [
      "interpolate",
      ["linear"],
      ["heatmap-density"],
      0,
      "rgba(0,0,255,0)",
      0.1,
      "royalblue",
      0.3,
      "cyan",
      0.5,
      "lime",
      0.7,
      "yellow",
      1,
      "red",
    ],
    "heatmap-radius": 20,
    "heatmap-opacity": 0.8,
  },
});

Event Handling

Map Events

// Map loaded
map.on("load", () => {
  console.log("Map loaded");
});

// Map moved
map.on("move", () => {
  console.log("Map is moving");
});

// Zoom changed
map.on("zoom", () => {
  console.log(`Zoom level: ${map.getZoom()}`);
});

// Map clicked
map.on("click", (e) => {
  console.log(`Clicked at: ${e.lngLat.lng}, ${e.lngLat.lat}`);
});

Layer Events

// Click on layer
map.on("click", "poi-layer", (e) => {
  const feature = e.features[0];
  console.log("Clicked feature:", feature.properties);
});

// Hover on layer
map.on("mouseenter", "poi-layer", (e) => {
  map.getCanvas().style.cursor = "pointer";

  // Optional: highlight feature
  if (e.features.length > 0) {
    const feature = e.features[0];
    map.setFeatureState({ source: "points", id: feature.id }, { hover: true });
  }
});

map.on("mouseleave", "poi-layer", () => {
  map.getCanvas().style.cursor = "";
});

Controls

Navigation Control

map.addControl(new maplibregl.NavigationControl(), "top-right");

Scale Control

map.addControl(
  new maplibregl.ScaleControl({
    maxWidth: 100,
    unit: "metric", // or 'imperial'
  }),
  "bottom-left"
);

Fullscreen Control

map.addControl(new maplibregl.FullscreenControl(), "top-right");

Geolocate Control

const geolocate = new maplibregl.GeolocateControl({
  positionOptions: {
    enableHighAccuracy: true,
  },
  trackUserLocation: true,
  showUserHeading: true,
});

map.addControl(geolocate, "top-right");

// Trigger on load
map.on("load", () => {
  geolocate.trigger();
});

Custom Control

class CustomControl {
  onAdd(map) {
    this._map = map;
    this._container = document.createElement("div");
    this._container.className = "maplibregl-ctrl";

    const button = document.createElement("button");
    button.textContent = "Custom Action";
    button.onclick = () => {
      console.log("Custom control clicked");
    };

    this._container.appendChild(button);
    return this._container;
  }

  onRemove() {
    this._container.parentNode.removeChild(this._container);
    this._map = undefined;
  }
}

map.addControl(new CustomControl(), "top-left");

Best Practices

Wait for Map Load

// ✅ Good: Wait for map to load
map.on("load", () => {
  map.addSource("data", {
    /* ... */
  });
  map.addLayer({
    /* ... */
  });
});

// ❌ Bad: Don't add layers immediately
map.addLayer({
  /* ... */
}); // May fail if map isn't loaded

Remove Event Listeners

function handleClick(e) {
  console.log("Clicked:", e.lngLat);
}

// Add listener
map.on("click", handleClick);

// Remove when done
map.off("click", handleClick);

Clean Up on Unmount

// React example
useEffect(() => {
  const map = new maplibregl.Map({
    /* ... */
  });

  return () => {
    map.remove(); // Clean up
  };
}, []);

Performance: Use Clustering

map.addSource("earthquakes", {
  type: "geojson",
  data: "/earthquakes.geojson",
  cluster: true,
  clusterMaxZoom: 14,
  clusterRadius: 50,
});

// Cluster circles
map.addLayer({
  id: "clusters",
  type: "circle",
  source: "earthquakes",
  filter: ["has", "point_count"],
  paint: {
    "circle-color": [
      "step",
      ["get", "point_count"],
      "#51bbd6",
      100,
      "#f1f075",
      750,
      "#f28cb1",
    ],
    "circle-radius": ["step", ["get", "point_count"], 20, 100, 30, 750, 40],
  },
});

// Cluster count
map.addLayer({
  id: "cluster-count",
  type: "symbol",
  source: "earthquakes",
  filter: ["has", "point_count"],
  layout: {
    "text-field": "{point_count_abbreviated}",
    "text-font": ["DIN Offc Pro Medium"],
    "text-size": 12,
  },
});

Common Patterns

Loading Indicator

const loader = document.getElementById("loader");

map.on("dataloading", () => {
  loader.style.display = "block";
});

map.on("idle", () => {
  loader.style.display = "none";
});

Query Features

// Query rendered features at a point
map.on("click", (e) => {
  const features = map.queryRenderedFeatures(e.point, {
    layers: ["poi-layer"],
  });

  if (features.length > 0) {
    console.log("Found features:", features);
  }
});

// Query all features from a source
const features = map.querySourceFeatures("my-source", {
  sourceLayer: "my-source-layer",
  filter: ["==", "type", "restaurant"],
});

Reference Documentation

For detailed API reference, advanced patterns, and examples:

• API Reference: Complete Map, Marker, Popup API
• Examples: Common use cases and patterns

Troubleshooting

Map Not Displaying

// Check container has dimensions
#map {
  width: 100%;
  height: 500px; /* Must have explicit height */
}

// Check style is loaded
map.on('error', (e) => {
  console.error('Map error:', e);
});

Images Not Loading

// Load image before using in layer
map.loadImage("/icon.png", (error, image) => {
  if (error) {
    console.error("Failed to load image:", error);
    return;
  }
  map.addImage("custom-icon", image);
});

TypeScript Errors

// Import types
import maplibregl, { Map, Marker, Popup } from "maplibre-gl";

// Type the map
const map: Map = new maplibregl.Map({
  /* ... */
});

Quick Reference

// Installation
bun add maplibre-gl

// Basic map
import maplibregl from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = new maplibregl.Map({
  container: 'map',
  style: 'https://demotiles.maplibre.org/style.json',
  center: [0, 0],
  zoom: 2
});

// Add marker
new maplibregl.Marker()
  .setLngLat([0, 0])
  .addTo(map);

// Add popup
new maplibregl.Popup()
  .setLngLat([0, 0])
  .setHTML('<h3>Hello</h3>')
  .addTo(map);

// Add GeoJSON
map.on('load', () => {
  map.addSource('data', {
    type: 'geojson',
    data: geojsonData
  });

  map.addLayer({
    id: 'layer',
    type: 'circle',
    source: 'data'
  });
});