/web-maps-mapbox

name: web-maps-mapbox
description: Mapbox GL JS interactive maps - map initialization, markers, popups, sources, layers, expressions, clustering, 3D terrain, geocoding, directions

Mapbox GL JS Patterns

> **Quick Guide:** Use Mapbox GL JS v3 for interactive vector maps. Initialize with `new mapboxgl.Map()`, add data via sources (GeoJSON, vector), visualize with layers (fill, line, circle, symbol, fill-extrusion, heatmap), style dynamically with expressions. Use the Standard style as the default base with slots (`bottom`, `middle`, `top`) for layer placement. Enable clustering on GeoJSON sources for large point datasets. Use `setTerrain` + `setFog` for 3D terrain. Types are included in the `mapbox-gl` package (no `@types/mapbox-gl` needed).

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST add sources before layers that reference them -- adding a layer without its source throws a runtime error)**

**(You MUST listen for `load` or `style.load` before calling `addSource`/`addLayer` -- the style is not ready on construction)**

**(You MUST clean up map instances with `map.remove()` on unmount -- leaks GPU memory and event listeners)**

**(You MUST use named constants for coordinates, zoom levels, and style values -- NO magic numbers)**

**(You MUST use expressions for data-driven styling instead of iterating features and setting styles individually)**

</critical_requirements>

---

**Auto-detection:** Mapbox, mapbox-gl, mapboxgl, Map, Marker, Popup, NavigationControl, GeolocateControl, addSource, addLayer, GeoJSON source, vector source, expressions, flyTo, easeTo, fitBounds, setTerrain, setFog, fill-extrusion, clustering, slot, Standard style, mapbox-gl-geocoder, mapbox-gl-directions, mapbox-gl-draw

**When to use:**

• Rendering interactive vector tile maps with custom styling
• Displaying point/line/polygon data on a map with data-driven styling
• Building map-based UIs with markers, popups, and custom controls
• Visualizing large datasets with clustering, heatmaps, or 3D extrusions
• Adding geocoding search, routing directions, or drawing tools
• Creating 3D terrain visualizations with elevation data

**When NOT to use:**

• Static map images without interactivity (use Mapbox Static Images API)
• Simple embedded maps without custom data (a basic iframe embed suffices)
• Applications requiring offline-only maps without a Mapbox access token

**Key patterns covered:**

• Map initialization with Standard style and access token
• Markers, popups, and built-in controls
• Source/layer model (GeoJSON, vector, raster-dem)
• Expression-based data-driven styling
• Clustering with automatic expansion on click
• 3D terrain, fog, and fill-extrusion buildings
• Camera animation (flyTo, easeTo, fitBounds)
• Event handling (click, mouseenter, mouseleave on layers)
• v3 slot system and Standard style configuration

---

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Map setup, markers, popups, controls, events, camera animation
• [examples/layers.md](examples/layers.md) - Sources, layers, expressions, clustering, data-driven styling
• [examples/interaction.md](examples/interaction.md) - 3D terrain, fog, fill-extrusion, drawing, geocoding, directions
• [reference.md](reference.md) - Decision frameworks, layer types, expression operators, anti-patterns

---

<philosophy>

Philosophy

Mapbox GL JS renders vector tiles on the GPU using WebGL 2, enabling smooth 60fps map interactions with large datasets. The core mental model is **sources + layers + expressions**:

1. **Sources** hold the data (GeoJSON, vector tiles, raster tiles, images) 2. **Layers** define how to visualize sources (fill, line, circle, symbol, fill-extrusion, heatmap, raster) 3. **Expressions** make layers data-driven (color by property, size by zoom, filter by attribute)

This separation means one source can power multiple layers (e.g., same GeoJSON rendered as both a fill layer and a line layer for borders), and layers can be styled entirely through expressions without touching the data.

**v3 Standard style:** The default style is `mapbox://styles/mapbox/standard`, which includes 3D buildings, terrain-aware rendering, and a slot system (`bottom`, `middle`, `top`) for inserting custom layers at predetermined positions in the visual stack. Use `setConfigProperty` to customize the Standard style's appearance without replacing it.

**TypeScript:** Types are bundled with `mapbox-gl` since v3 -- do not install `@types/mapbox-gl`.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Map Initialization

Initialize with container, style, center, zoom. Always wait for `load` event before adding sources/layers.

import mapboxgl from "mapbox-gl";
import "mapbox-gl/dist/mapbox-gl.css";

const DEFAULT_CENTER: [number, number] = [-74.006, 40.7128]; // [lng, lat]
const DEFAULT_ZOOM = 12;

mapboxgl.accessToken = process.env.MAPBOX_ACCESS_TOKEN!;

const map = new mapboxgl.Map({
  container: "map", // HTML element ID or element reference
  style: "mapbox://styles/mapbox/standard",
  center: DEFAULT_CENTER,
  zoom: DEFAULT_ZOOM,
});

map.on("load", () => {
  // Safe to add sources and layers here
});

**Why good:** Named constants for coordinates/zoom, waits for `load` before data operations, uses Standard style

See [examples/core.md](examples/core.md) Pattern 1 for cleanup patterns and bad examples.

---

Pattern 2: Markers, Popups, and Controls

Markers are DOM elements placed at coordinates. Popups display content on click. Controls add navigation UI.

const MARKER_COLOR = "#e74c3c";

const popup = new mapboxgl.Popup({ offset: 25, maxWidth: "300px" })
  .setHTML("<h3>Location</h3><p>Description</p>");

new mapboxgl.Marker({ color: MARKER_COLOR })
  .setLngLat([-74.006, 40.7128])
  .setPopup(popup)
  .addTo(