/web-maps-mapbox

name: web-maps-mapbox
description: Mapbox GL JS interactive vector maps. Use when building a map with sources and layers, expressions, clustering, 3D terrain, geocoding or directions.

Mapbox GL JS Patterns

> **Quick Guide:** Mapbox GL JS renders vector tiles on the GPU, and the whole mental model is > **sources hold data, layers visualize them, expressions make the visualization data-driven**. One > source can feed several layers, and a layer's appearance is decided by a JSON expression rather > than by JavaScript touching features. Everything that adds data waits for the style — `load` or > `style.load` — because the map has no style at construction. Clustering is a flag on a GeoJSON > source, not a plugin. **Current: v3**, where the Standard style is the default and custom layers > are placed into named slots rather than before a layer id.

**Detailed Resources:**

• [examples/core.md](examples/core.md) — map setup and cleanup, markers, popups, controls, camera animation, feature-state hover, custom controls
• [examples/layers.md](examples/layers.md) — sources, every layer type, expressions, filters, clustering, safe removal
• [examples/interaction.md](examples/interaction.md) — 3D terrain, fog, fill-extrusion, heatmaps, geocoder and directions plugins, `queryRenderedFeatures`, image sources
• [reference.md](reference.md) — v3 migration, slots and configuration, layer and source tables, the full expression operator list, event table, performance tuning

---

Which path applies

• **The Standard style** (v3's default, `mapbox://styles/mapbox/standard`) — place custom layers with

`slot: "bottom" | "middle" | "top"`, and change the basemap's own appearance through `setConfigProperty` rather than by editing its layers.

• **A classic or custom style** — there are no slots; `addLayer(layer, beforeId)` positions a layer

relative to an existing one, which means reading `map.getStyle().layers` to find the id.

• **Terrain, fog or anything that must survive a style switch** — register it on `style.load`, which

fires again on every `setStyle`, rather than on `load`, which fires once. See [examples/interaction.md](examples/interaction.md).

---

<critical_requirements>

Before writing Mapbox GL JS code

**Add a source before any layer that references it.** A layer naming a source that does not exist throws, and layers cannot be reordered around that.

**Do source and layer work inside a `load` or `style.load` handler.** The map has no style when the constructor returns, so `addSource` immediately after `new mapboxgl.Map()` fails with "Style is not done loading".

**Call `map.remove()` when the map goes away.** It releases the WebGL context, and browsers cap how many can exist at once — a leaked map makes the next one fail to initialize.

**Style with expressions rather than by looping over features.** An expression runs on the GPU for every feature at once; a JavaScript loop that sets styles individually gives up the rendering model the library exists for.

**Put untrusted content through `setText()` or `setDOMContent()`.** `Popup.setHTML()` renders what it is given without sanitizing it.

</critical_requirements>

---

**Auto-detection:** Mapbox, mapbox-gl, mapboxgl, `mapboxgl.Map`, `mapboxgl.Marker`, `mapboxgl.Popup`, NavigationControl, GeolocateControl, ScaleControl, addSource, addLayer, setPaintProperty, setLayoutProperty, setFilter, setFeatureState, queryRenderedFeatures, querySourceFeatures, getClusterExpansionZoom, fill-extrusion, raster-dem, setTerrain, setFog, setConfigProperty, `mapbox://styles/mapbox/standard`, `@mapbox/mapbox-gl-geocoder`, `@mapbox/mapbox-gl-directions`, `@mapbox/mapbox-gl-draw`

**Applies to:**

• Interactive vector maps with custom styling
• Point, line and polygon data styled from its own properties
• Markers, popups and map controls, including custom ones through `IControl`
• Large datasets through clustering, heatmaps and GPU-rendered layers
• 3D — terrain, fog, extruded buildings
• Camera animation and layer-scoped event handling
• The Standard style's slot system and configuration API

**Handled elsewhere:**

• Where the GeoJSON comes from — a source takes an object or a URL, and fetching, caching and paging

it are not the map's concern

• Sanitizing content before it reaches `setHTML` — the popup renders raw markup and cleans nothing
• Provisioning and restricting the access token — the map reads a token, and where it is stored and

what it is scoped to is a deployment decision

• How markers, popups and controls look — the library supplies elements and class names, and the CSS

in them is settled by whatever owns styling

• Rendering a map as a static image server-side — this is a WebGL client

---

<philosophy>

**Sources, layers, expressions**, and the separation between them is the point:

1. **Sources** hold data — GeoJSON, vector tiles, raster tiles, elevation, images 2. **Layers** decide how a source is drawn — fill, line, circle, symbol, fill-extrusion, heatmap, raster 3. **Expressions** make a layer data-driven — colour by property, size by zoom, filter by attribute

So one GeoJSON source can be a fill layer and a line layer at once, and restyling is a change to a layer's paint properties with the data untouched.

**Styling is declarative and runs on the GPU.** An expression is a JSON array evaluated per feature per frame by the renderer, which is why the same expression costs the same on ten features and on a hundred thousand.

**The style is a document the map loads**, and the Standard style in v3 is a live one: slots are the insertion points it publishes for your layers, and `setConfigProperty` is how you change what it draws without knowing what is inside it.

</philosophy>

---

<decision_framework>

Which layer type

Points
├─ Fewer than ~100, with custom HTML?   → Markers (DOM elements)
├─ Many, or styled from data?           → circle layer, or symbol for icons and labels
└─ Density rather than individuals?