mapbox-integration-patterns

Vue Integration

Pattern: mounted + unmounted lifecycle hooks

Key points:

Initialize in mounted() hook Access container via this.$refs.mapContainer Store map as this.map Always implement unmounted() hook to call map.remove() Svelte Integration

Pattern: onMount + onDestroy

Key points:

Use onMount for initialization Bind container with bind:this={mapContainer} Always implement onDestroy to call map.remove() Can pass accessToken directly to Map constructor in Svelte Angular Integration

Pattern: ngOnInit + ngOnDestroy with SSR handling

import { Component, ElementRef, OnDestroy, OnInit, ViewChild, inject } from '@angular/core'; import { isPlatformBrowser, CommonModule } from '@angular/common'; import { PLATFORM_ID } from '@angular/core'; import { environment } from '../../environments/environment';

@Component({ selector: 'app-map', standalone: true, imports: [CommonModule], templateUrl: './map.component.html', styleUrls: ['./map.component.scss'] }) export class MapComponent implements OnInit, OnDestroy { @ViewChild('mapContainer', { static: false }) mapContainer!: ElementRef;

private map: any; private readonly platformId = inject(PLATFORM_ID);

async ngOnInit(): Promise { // IMPORTANT: Check if running in browser (not SSR) if (!isPlatformBrowser(this.platformId)) { return; }

try {
  await this.initializeMap();
} catch (error) {
  console.error('Failed to initialize map:', error);
}

}

private async initializeMap(): Promise { // Dynamically import to avoid SSR issues const mapboxgl = (await import('mapbox-gl')).default;

this.map = new mapboxgl.Map({
  accessToken: environment.mapboxAccessToken,
  container: this.mapContainer.nativeElement,
  center: [-71.05953, 42.3629],
  zoom: 13
});

// Handle map errors
this.map.on('error', (e: any) => console.error('Map error:', e.error));

}

// CRITICAL: Clean up on component destroy ngOnDestroy(): void { if (this.map) { this.map.remove(); } } }

Template (map.component.html):

Key points:

Use @ViewChild to reference map container Check isPlatformBrowser before initializing (SSR support) Dynamically import mapbox-gl to avoid SSR issues Initialize in ngOnInit() lifecycle hook Always implement ngOnDestroy() to call map.remove() Handle errors with map.on('error', ...) Vanilla JavaScript (with Vite)

Pattern: Module imports with initialization function

import mapboxgl from 'mapbox-gl'; import 'mapbox-gl/dist/mapbox-gl.css'; import './main.css';

// Set access token mapboxgl.accessToken = import.meta.env.VITE_MAPBOX_ACCESS_TOKEN;

let map;

/* * Initialize the map / function initMap() { map = new mapboxgl.Map({ container: 'map-container', center: [-71.05953, 42.3629], zoom: 13 });

map.on('load', () => { console.log('Map is loaded'); }); }

// Initialize when script runs initMap();

HTML:

Key points:

Store map in module-scoped variable Initialize immediately or on DOMContentLoaded Listen for 'load' event for post-initialization actions Vanilla JavaScript (No Bundler - CDN)

Pattern: Script tag with inline initialization

⚠️ Note: This pattern is for prototyping only. Production apps should use npm/bundler for version control and offline builds.

Key points:

⚠️ Prototyping only - not recommended for production Replace 3.x.x with specific version (e.g., 3.7.0) from Mapbox docs Don't use /latest/ - always pin to specific version for consistency Initialize after script loads (bottom of body) For production: Use npm + bundler instead

Why not CDN for production?

❌ Network dependency (breaks offline) ❌ No version locking (CDN could change) ❌ Slower (no bundler optimization) ❌ No tree-shaking ✅ Use npm for production: npm install mapbox-gl@^3.0.0 Token Management Patterns Environment Variables (Recommended)

Different frameworks use different prefixes for client-side environment variables:

Framework/Bundler Environment Variable Access Pattern Vite VITE_MAPBOX_ACCESS_TOKEN import.meta.env.VITE_MAPBOX_ACCESS_TOKEN Next.js NEXT_PUBLIC_MAPBOX_TOKEN process.env.NEXT_PUBLIC_MAPBOX_TOKEN Create React App REACT_APP_MAPBOX_TOKEN process.env.REACT_APP_MAPBOX_TOKEN Angular environment.mapboxAccessToken Environment files (environment.ts)

Vite .env file:

VITE_MAPBOX_ACCESS_TOKEN=pk.eyJ1...

Next.js .env.local file:

NEXT_PUBLIC_MAPBOX_TOKEN=pk.eyJ1...

Important:

✅ Always use environment variables for tokens ✅ Never commit .env files to version control ✅ Use public tokens (pk.*) for client-side apps ✅ Add .env to .gitignore ✅ Provide .env.example template for team

.gitignore:

.env .env.local .env.*.local

.env.example:

VITE_MAPBOX_ACCESS_TOKEN=your_token_here

Mapbox Search JS Integration Search Box Component Pattern

Install dependency:

npm install @mapbox/search-js-react # React npm install @mapbox/search-js-web # Vanilla/Vue/Svelte

Note: Both packages include @mapbox/search-js-core as a dependency. You only need to install -core directly if building a custom search UI.

React Search Pattern:

import { SearchBox } from '@mapbox/search-js-react';

// Inside component: setInputValue(value)} proximity={centerCoordinates} // Bias results near center marker // Show marker for selected result />;

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):

Common positions:

Top-right: top: 10px, right: 10px Top-left: top: 10px, left: 10px Bottom-left: bottom: 10px, left: 10px Common Mistakes to Avoid ❌ Mistake 1: Forgetting to call map.remove() // BAD - Memory leak! useEffect(() => { const map = new mapboxgl.Map({ ... }) // No cleanup function }, [])

// GOOD - Proper cleanup useEffect(() => { const map = new mapboxgl.Map({ ... }) return () => map.remove() // ✅ Cleanup }, [])

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 // BAD - Infinite loop in React! function MapComponent() { const map = new mapboxgl.Map({ ... }) // Runs on every render return

mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_TOKEN!

mapRef.current = new mapboxgl.Map({
  container: mapContainerRef.current,
  center: [-71.05953, 42.36290],
  zoom: 13
})

return () => mapRef.current?.remove()