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    # Installs latest v3.x

CDN (for prototyping only):

<!-- Replace VERSION with latest v3.x from https://docs.mapbox.com/mapbox-gl-js/ -->
<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      # React
npm install @mapbox/search-js-web@^1.0.0        # Other frameworks

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; // Use env vars in production

// Global token (works since v1.x)
mapboxgl.accessToken = token;
const map = new mapboxgl.Map({ container: '...' });

// Per-map token (preferred for multi-map setups)
const map = new mapboxgl.Map({
  accessToken: token,
  container: '...'
});

Core Principles

Every Mapbox GL JS integration must:

1. Initialize the map in the correct lifecycle hook
2. Store map instance in component state (not recreate on every render)
3. Always call map.remove() on cleanup to prevent memory leaks
4. Handle token management securely (environment variables)
5. 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); // Store map instance
  const mapContainerRef = useRef(null); // Store DOM reference

  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
    });

    // CRITICAL: Cleanup to prevent memory leaks
    return () => {
      mapRef.current.remove();
    };
  }, []); // Empty dependency array = run once on mount

  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
        }