| name | mapbox-web-integration-patterns |
| description | 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. |
Mapbox Integration Patterns Skill
This 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.
Version Requirements
Mapbox GL JS
Recommended: v3.x (latest)
- Minimum: v3.0.0
- Why v3.x: Modern API, improved performance, active development
- v2.x: Legacy; no longer actively developed (see migration notes below)
Installing via npm (recommended for production):
npm install mapbox-gl@^3.0.0
CDN (for prototyping only):
<script src="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.js"></script>
<link href="https://api.mapbox.com/mapbox-gl-js/vVERSION/mapbox-gl.css" rel="stylesheet" />
Framework Requirements
React: GL JS works with React 16.8+ (requires hooks). create-web-app scaffolds with React 19.x.
Vue: GL JS works with Vue 2.x+ (Vue 3 Composition API recommended).
Svelte: GL JS works with any Svelte version. create-web-app scaffolds with Svelte 5.x.
Angular: GL JS works with Angular 2+. create-web-app scaffolds with Angular 19.x.
Next.js: Minimum 13.x (App Router), Pages Router 12.x+.
Mapbox Search JS
npm install @mapbox/search-js-react@^1.0.0
npm install @mapbox/search-js-web@^1.0.0
Version Migration Notes (v2.x to v3.x)
- WebGL 2 now required
optimizeForTerrain option removed
- Improved TypeScript types, better tree-shaking support
- No breaking changes to core initialization patterns
Token patterns (work in v2.x and v3.x):
const token = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: '...' });
const map = new mapboxgl.Map({
accessToken: token,
container: '...'
});
Core Principles
Every Mapbox GL JS integration must:
- Initialize the map in the correct lifecycle hook
- Store map instance in component state (not recreate on every render)
- Always call
map.remove() on cleanup to prevent memory leaks
- Handle token management securely (environment variables)
- Import CSS:
import 'mapbox-gl/dist/mapbox-gl.css'
React Integration (Primary Pattern)
Pattern: useRef + useEffect with cleanup
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 for other bundlers.
import { useRef, useEffect } from 'react';
import mapboxgl from 'mapbox-gl';
import 'mapbox-gl/dist/mapbox-gl.css';
function MapComponent() {
const mapRef = useRef(null);
const mapContainerRef = useRef(null);
useEffect(() => {
mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: [-71.05953, 42.3629],
zoom: 13
});
return () => {
mapRef.current.remove();
};
}, []);
return <div ref={mapContainerRef} style={{ height: '100vh' }} />;
}
Key points:
- Use
useRef for both map instance and container
- Initialize in
useEffect with empty deps []
- Always return cleanup function that calls
map.remove()
- Never initialize map in render (causes infinite loops)
React + Search JS
import { useRef, useEffect, useState } from 'react';
import mapboxgl from 'mapbox-gl';
import { SearchBox } from '@mapbox/search-js-react';
import 'mapbox-gl/dist/mapbox-gl.css';
const accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;
const center = [-71.05953, 42.3629];
function MapWithSearch() {
const mapRef = useRef(null);
const mapContainerRef = useRef(null);
const [inputValue, setInputValue] = useState('');
useEffect(() => {
mapboxgl.accessToken = accessToken;
mapRef.current = new mapboxgl.Map({
container: mapContainerRef.current,
center: center,
zoom: 13
});
return () => {
mapRef.current.remove();
};
}, []);
return (
<>
<div
style={{
margin: '10px 10px 0 0',
width: 300,
right: 0,
top: 0,
position: 'absolute',
zIndex: 10
}}
>
<SearchBox
accessToken={accessToken}
map={mapRef.current}
mapboxgl={mapboxgl}
value={inputValue}
proximity={center}
onChange={(d) => setInputValue(d)}
marker
/>
</div>
<div ref={mapContainerRef} style={{ height: '100vh' }} />
</>
);
}
Search JS Integration Summary
Install:
npm install @mapbox/search-js-react
npm install @mapbox/search-js-web
Both packages include @mapbox/search-js-core as a dependency. Only install -core directly if building a custom search UI.
Key configuration options:
accessToken: Your Mapbox public token
map: Map instance (must be initialized first)
mapboxgl: The mapboxgl library reference
proximity: [lng, lat] to bias results geographically
marker: Boolean to show/hide result marker
placeholder: Search box placeholder text
Positioning Search Box
Absolute positioning (overlay):
<div
style={{
position: 'absolute',
top: 10,
right: 10,
zIndex: 10,
width: 300
}}
>
<SearchBox {...props} />
</div>
Common positions:
- Top-right:
top: 10px, right: 10px
- Top-left:
top: 10px, left: 10px
- Bottom-left:
bottom: 10px, left: 10px
Common Mistakes (Critical)
Mistake 1: Forgetting to call map.remove()
useEffect(() => {
const map = new mapboxgl.Map({ ... })
}, [])
useEffect(() => {
const map = new mapboxgl.Map({ ... })
return () => map.remove()
}, [])
Why: Every Map instance creates WebGL contexts, event listeners, and DOM nodes. Without cleanup, these accumulate and cause memory leaks.
Mistake 2: Initializing map in render
function MapComponent() {
const map = new mapboxgl.Map({ ... })
return <div />
}
function MapComponent() {
useEffect(() => {
const map = new mapboxgl.Map({ ... })
}, [])
return <div />
}
Why: React components re-render frequently. Creating a new map on every render causes infinite loops and crashes.
Mistake 3: Not storing map instance properly
function MapComponent() {
useEffect(() => {
let map = new mapboxgl.Map({ ... })
}, [])
}
function MapComponent() {
const mapRef = useRef()
useEffect(() => {
mapRef.current = new mapboxgl.Map({ ... })
}, [])
}
Why: You need to access the map instance for operations like adding layers, markers, or calling remove().
Mistake 4: Storing map instance in Vue's data() (Vue-specific)
export default {
data() {
return {
map: null
}
},
mounted() {
this.map = new mapboxgl.Map({ ... })
}
}
export default {
mounted() {
this.map = new mapboxgl.Map({
container: this.$refs.mapContainer,
center: [-71.05953, 42.3629],
zoom: 13
})
},
unmounted() {
this.map?.remove()
}
}
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.
Reference Files
Load these for framework-specific patterns and additional details:
references/vue.md — Vue Integration (mounted/unmounted lifecycle)
references/svelte.md — Svelte Integration (onMount/onDestroy)
references/angular.md — Angular Integration with SSR handling
references/vanilla.md — Vanilla JS (Vite) + Vanilla JS (CDN)
references/web-components.md — Web Components (basic + reactive + usage in React/Vue/Svelte)
references/nextjs.md — Next.js App Router + Pages Router
references/common-mistakes.md — Common Mistakes 4-7 + Testing Patterns
references/token-management.md — Token Management per bundler + Style Configuration
When to Use This Skill
Invoke this skill when:
- Setting up Mapbox GL JS in a new project
- Integrating Mapbox into a specific framework (React, Vue, Svelte, Angular, Next.js)
- Building framework-agnostic Web Components
- Creating reusable map components for component libraries
- Debugging map initialization issues
- Adding Mapbox Search functionality
- Implementing proper cleanup and lifecycle management
- Converting between frameworks (e.g., React to Vue)
- Reviewing code for Mapbox integration best practices
Related Skills
- mapbox-cartography: Map design principles and styling
- mapbox-token-security: Token management and security
- mapbox-style-patterns: Common map style patterns
Resources