Mapbox Web Integration Patterns

1---2name: mapbox-web-integration-patterns3description: Official integration patterns for Mapbox GL JS across popular web frameworks (React, Vue, Svelte, Angular). Covers setup, lifecycle management, token handling, search integration, and common pitfalls. Based on Mapbox's create-web-app scaffolding tool.4---5 6# Mapbox Integration Patterns Skill7 8This skill provides official patterns for integrating Mapbox GL JS into web applications using React, Vue, Svelte, Angular, and vanilla JavaScript. These patterns are based on Mapbox's `create-web-app` scaffolding tool and represent production-ready best practices.9 10## Version Requirements11 12### Mapbox GL JS13 14**Recommended:** v3.x (latest)15 16- **Minimum:** v3.0.017- **Why v3.x:** Modern API, improved performance, active development18- **v2.x:** Legacy; no longer actively developed (see migration notes below)19 20**Installing via npm (recommended for production):**21 22```bash23npm install mapbox-gl@^3.0.0    # Installs latest v3.x24```25 26**CDN (for prototyping only):**27 28```html29<!-- Replace VERSION with latest v3.x from https://docs.mapbox.com/mapbox-gl-js/ -->30<script src="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.js"></script>31<link href="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.css" rel="stylesheet" />32```33 34### Framework Requirements35 36**React:** GL JS works with React 16.8+ (requires hooks). `create-web-app` scaffolds with React 19.x.37**Vue:** GL JS works with Vue 2.x+ (Vue 3 Composition API recommended).38**Svelte:** GL JS works with any Svelte version. `create-web-app` scaffolds with Svelte 5.x.39**Angular:** GL JS works with Angular 2+. `create-web-app` scaffolds with Angular 19.x.40**Next.js:** Minimum 13.x (App Router), Pages Router 12.x+.41 42### Mapbox Search JS43 44```bash45npm install @mapbox/search-js-react@^1.0.0      # React46npm install @mapbox/search-js-web@^1.0.0        # Other frameworks47```48 49### Version Migration Notes (v2.x to v3.x)50 51- WebGL 2 now required52- `optimizeForTerrain` option removed53- Improved TypeScript types, better tree-shaking support54- No breaking changes to core initialization patterns55 56**Token patterns (work in v2.x and v3.x):**57 58```javascript59const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN; // Use env vars in production60 61// Global token (works since v1.x)62mapboxgl.accessToken = token;63const map = new mapboxgl.Map({ container: '...' });64 65// Per-map token (preferred for multi-map setups)66const map = new mapboxgl.Map({67  accessToken: token,68  container: '...'69});70```71 72## Core Principles73 74**Every Mapbox GL JS integration must:**75 761. Initialize the map in the correct lifecycle hook772. Store map instance in component state (not recreate on every render)783. **Always call `map.remove()` on cleanup** to prevent memory leaks794. Handle token management securely (environment variables)805. Import CSS: `import 'mapbox-gl/dist/mapbox-gl.css'`81 82## React Integration (Primary Pattern)83 84**Pattern: useRef + useEffect with cleanup**85 86> **Note:** These examples use **Vite** (the bundler used in `create-web-app`). If using Create React App, replace `import.meta.env.VITE_MAPBOX_ACCESS_TOKEN` with `process.env.REACT_APP_MAPBOX_TOKEN`. See [Token Management Patterns](references/token-management.md) for other bundlers.87 88```jsx89import { useRef, useEffect } from 'react';90import mapboxgl from 'mapbox-gl';91import 'mapbox-gl/dist/mapbox-gl.css';92 93function MapComponent() {94  const mapRef = useRef(null); // Store map instance95  const mapContainerRef = useRef(null); // Store DOM reference96 97  useEffect(() => {98    mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;99 100    mapRef.current = new mapboxgl.Map({101      container: mapContainerRef.current,102      center: [-71.05953, 42.3629],103      zoom: 13104    });105 106    // CRITICAL: Cleanup to prevent memory leaks107    return () => {108      mapRef.current.remove();109    };110  }, []); // Empty dependency array = run once on mount111 112  return <div ref={mapContainerRef} style={{ height: '100vh' }} />;113}114```115 116**Key points:**117 118- Use `useRef` for both map instance and container119- Initialize in `useEffect` with empty deps `[]`120- **Always return cleanup function** that calls `map.remove()`121- Never initialize map in render (causes infinite loops)122 123### React + Search JS124 125```jsx126import { useRef, useEffect, useState } from 'react';127import mapboxgl from 'mapbox-gl';128import { SearchBox } from '@mapbox/search-js-react';129import 'mapbox-gl/dist/mapbox-gl.css';130 131const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;132const center = [-71.05953, 42.3629];133 134function MapWithSearch() {135  const mapRef = useRef(null);136  const mapContainerRef = useRef(null);137  const [inputValue, setInputValue] = useState('');138 139  useEffect(() => {140    mapboxgl.accessToken = accessToken;141 142    mapRef.current = new mapboxgl.Map({143      container: mapContainerRef.current,144      center: center,145      zoom: 13146    });147 148    return () => {149      mapRef.current.remove();150    };151  }, []);152 153  return (154    <>155      <div156        style={{157          margin: '10px 10px 0 0',158          width: 300,159          right: 0,160          top: 0,161          position: 'absolute',162          zIndex: 10163        }}164      >165        <SearchBox166          accessToken={accessToken}167          map={mapRef.current}168          mapboxgl={mapboxgl}169          value={inputValue}170          proximity={center}171          onChange={(d) => setInputValue(d)}172          marker173        />174      </div>175      <div ref={mapContainerRef} style={{ height: '100vh' }} />176    </>177  );178}179```180 181## Search JS Integration Summary182 183**Install:**184 185```bash186npm install @mapbox/search-js-react      # React187npm install @mapbox/search-js-web        # Vanilla/Vue/Svelte188```189 190Both packages include `@mapbox/search-js-core` as a dependency. Only install `-core` directly if building a custom search UI.191 192**Key configuration options:**193 194- `accessToken`: Your Mapbox public token195- `map`: Map instance (must be initialized first)196- `mapboxgl`: The mapboxgl library reference197- `proximity`: `[lng, lat]` to bias results geographically198- `marker`: Boolean to show/hide result marker199- `placeholder`: Search box placeholder text200 201### Positioning Search Box202 203**Absolute positioning (overlay):**204 205```jsx206<div207  style={{208    position: 'absolute',209    top: 10,210    right: 10,211    zIndex: 10,212    width: 300213  }}214>215  <SearchBox {...props} />216</div>217```218 219**Common positions:**220 221- Top-right: `top: 10px, right: 10px`222- Top-left: `top: 10px, left: 10px`223- Bottom-left: `bottom: 10px, left: 10px`224 225## Common Mistakes (Critical)226 227### Mistake 1: Forgetting to call map.remove()228 229```javascript230// BAD - Memory leak!231useEffect(() => {232  const map = new mapboxgl.Map({ ... })233  // No cleanup function234}, [])235 236// GOOD - Proper cleanup237useEffect(() => {238  const map = new mapboxgl.Map({ ... })239  return () => map.remove()  // Cleanup240}, [])241```242 243**Why:** Every Map instance creates WebGL contexts, event listeners, and DOM nodes. Without cleanup, these accumulate and cause memory leaks.244 245### Mistake 2: Initializing map in render246 247```javascript248// BAD - Infinite loop in React!249function MapComponent() {250  const map = new mapboxgl.Map({ ... })  // Runs on every render251  return <div />252}253 254// GOOD - Initialize in effect255function MapComponent() {256  useEffect(() => {257    const map = new mapboxgl.Map({ ... })258  }, [])259  return <div />260}261```262 263**Why:** React components re-render frequently. Creating a new map on every render causes infinite loops and crashes.264 265### Mistake 3: Not storing map instance properly266 267```javascript268// BAD - map variable lost between renders269function MapComponent() {270  useEffect(() => {271    let map = new mapboxgl.Map({ ... })272    // map variable is not accessible later273  }, [])274}275 276// GOOD - Store in useRef277function MapComponent() {278  const mapRef = useRef()279  useEffect(() => {280    mapRef.current = new mapboxgl.Map({ ... })281    // mapRef.current accessible throughout component282  }, [])283}284```285 286**Why:** You need to access the map instance for operations like adding layers, markers, or calling `remove()`.287 288### Mistake 4: Storing map instance in Vue's data() (Vue-specific)289 290```javascript291// BAD - Vue's reactivity wraps data() objects in a Proxy, breaking mapbox-gl internals!292export default {293  data() {294    return {295      map: null  // Will be wrapped in a Proxy296    }297  },298  mounted() {299    this.map = new mapboxgl.Map({ ... })  // Proxy breaks GL internals300  }301}302 303// GOOD - Assign map as a plain instance property, not in data()304export default {305  mounted() {306    this.map = new mapboxgl.Map({307      container: this.$refs.mapContainer,308      center: [-71.05953, 42.3629],309      zoom: 13310    })311  },312  unmounted() {313    this.map?.remove()314  }315}316```317 318**Why:** In Vue (especially Vue 3), `data()` properties are wrapped in a `Proxy` for reactivity. Mapbox GL JS internally checks object identity and uses properties that don't survive proxy wrapping. Storing the map in `data()` causes subtle, hard-to-debug failures. Instead, assign the map instance directly as `this.map` in `mounted()` — properties assigned outside `data()` are not made reactive.319 320## Reference Files321 322Load these for framework-specific patterns and additional details:323 324- `references/vue.md` — Vue Integration (mounted/unmounted lifecycle)325- `references/svelte.md` — Svelte Integration (onMount/onDestroy)326- `references/angular.md` — Angular Integration with SSR handling327- `references/vanilla.md` — Vanilla JS (Vite) + Vanilla JS (CDN)328- `references/web-components.md` — Web Components (basic + reactive + usage in React/Vue/Svelte)329- `references/nextjs.md` — Next.js App Router + Pages Router330- `references/common-mistakes.md` — Common Mistakes 4-7 + Testing Patterns331- `references/token-management.md` — Token Management per bundler + Style Configuration332 333## When to Use This Skill334 335Invoke this skill when:336 337- Setting up Mapbox GL JS in a new project338- Integrating Mapbox into a specific framework (React, Vue, Svelte, Angular, Next.js)339- Building framework-agnostic Web Components340- Creating reusable map components for component libraries341- Debugging map initialization issues342- Adding Mapbox Search functionality343- Implementing proper cleanup and lifecycle management344- Converting between frameworks (e.g., React to Vue)345- Reviewing code for Mapbox integration best practices346 347## Related Skills348 349- **mapbox-cartography**: Map design principles and styling350- **mapbox-token-security**: Token management and security351- **mapbox-style-patterns**: Common map style patterns352 353## Resources354 355- [Mapbox GL JS Documentation](https://docs.mapbox.com/mapbox-gl-js/)356- [Mapbox Search JS Documentation](https://docs.mapbox.com/mapbox-search-js/)357- [create-web-app GitHub](https://github.com/mapbox/create-web-app)