comparisonmapscomponents

Maps Component Face‑Off: Building A Modular Mapping UI That Chooses Between Google Maps and Waze Data

jjavascripts

2026-01-25

11 min read

Build a modular JS mapping component that switches between Google Maps, Waze incident overlays, and open tiles at runtime — with code and licensing notes.

Hook — Stop Rebuilding Mapping UI Logic Every Project

If your team wastes weeks integrating a map, wireframing incident overlays, and then redoing it when the client switches from Google to an open provider, you’re not alone. The real problem isn’t tiles or markers — it’s tight coupling between UI logic and a single provider’s SDK. In 2026, teams need modular, provider-agnostic mapping components that let product and legal teams swap data sources at runtime without rewriting the app.

The TL;DR — What You’ll Build and Why It Matters Now

This article shows a practical pattern and working code for a mapping component that uses an adapter layer to switch at runtime between:

Google Maps tiles and APIs (full raster/vector features via Google Maps Platform)
Waze incident overlays (data from Waze for Cities / Waze partners)
Open alternatives (MapLibre + OpenStreetMap/PMTiles tiles or commercial tile providers)

You’ll get: a small, framework-agnostic adapter API, runnable examples, integration notes for React/Vue, basic performance tradeoffs, and concise licensing considerations for procurement and legal review in 2026.

Why 2026 Is the Year for Adapter-First Mapping

Several trends that matured through late 2024–2025 make an adapter approach essential:

Vector tile proliferation (Mapbox Vector Tile and PMTiles adoption) — smaller payloads and client-side styling are mainstream.
Open rendering stacks (MapLibre stable forks and wide community support) — viable alternatives to vendor SDKs exist. See work on MapLibre adoption for edge-first architectures.
Data partnership models (Waze for Cities remains the go-to for live incident feeds) — incident data is valuable but often contract-restricted.
Cost and privacy pressure — engineering teams avoid vendor lock-in to control cloud bills and user data flows.

Architecture: The Adapter Pattern for Mapping

The key idea: isolate your UI and business logic from provider-specific code behind a small, stable adapter interface. The component interacts only with the adapter. Each adapter wraps an SDK (Google Maps, MapLibre, or a Waze overlay service).

Adapter responsibilities

init(container, options) — create and mount the map
setView(center, zoom) — change camera/center
addIncidentOverlay(data) — render Waze-style incidents (overlays)
clearOverlays() — remove incident overlays
destroy() — teardown and free resources

Minimal, Framework‑Agnostic Starter (Vanilla JS)

The example below is intentionally compact and runnable in a static page. It demonstrates adapters for Google Maps (tiles + base map), MapLibre (open tiles), and a Waze overlay adapter that can be plugged on top of either base provider.

// map-adapters.js

export class MapAdapterBase {
  constructor() { this.map = null }
  async init(container, opts) { throw new Error('init not implemented') }
  setView(center, zoom) { throw new Error('setView not implemented') }
  addIncidentOverlay(data) { throw new Error('addIncidentOverlay not implemented') }
  clearOverlays() { throw new Error('clearOverlays not implemented') }
  destroy() { throw new Error('destroy not implemented') }
}

// Google Maps adapter (requires loading Google Maps JS API externally)
export class GoogleAdapter extends MapAdapterBase {
  constructor(apiKey) { super(); this.apiKey = apiKey; this._overlays = [] }
  async init(container, opts = {}) {
    if (!window.google || !google.maps) throw new Error('Google Maps JS SDK not loaded')
    this.map = new google.maps.Map(container, {
      center: opts.center || { lat: 0, lng: 0 },
      zoom: opts.zoom || 2,
      disableDefaultUI: true
    })
  }
  setView(center, zoom) { this.map.setCenter(center); this.map.setZoom(zoom) }
  addIncidentOverlay(incidents) {
    // incidents: [{id, lat, lng, type, severity}]
    this.clearOverlays()
    incidents.forEach(i => {
      const marker = new google.maps.Marker({
        position: { lat: i.lat, lng: i.lng },
        map: this.map,
        title: i.type
      })
      this._overlays.push(marker)
    })
  }
  clearOverlays() { this._overlays.forEach(m => m.setMap(null)); this._overlays = [] }
  destroy() { this.clearOverlays(); this.map = null }
}

// MapLibre adapter (open alternative)
export class MapLibreAdapter extends MapAdapterBase {
  constructor(styleUrl = null) { super(); this.styleUrl = styleUrl; this._overlays = [] }
  async init(container, opts = {}) {
    // expects maplibre-gl to be available
    if (!window.maplibregl) throw new Error('maplibre-gl not loaded')
    this.map = new maplibregl.Map({
      container,
      style: this.styleUrl || opts.style || 'https://demotiles.maplibre.org/style.json',
      center: [opts.center?.lng || 0, opts.center?.lat || 0],
      zoom: opts.zoom || 2
    })
  }
  setView(center, zoom) { this.map.setCenter([center.lng, center.lat]); this.map.setZoom(zoom) }
  addIncidentOverlay(incidents) {
    this.clearOverlays()
    incidents.forEach(i => {
      const el = document.createElement('div')
      el.className = 'incident-marker'
      el.title = i.type
      el.style.width = '18px'; el.style.height = '18px'; el.style.background = 'rgba(255,0,0,0.8)'; el.style.borderRadius = '50%'
      const marker = new maplibregl.Marker(el).setLngLat([i.lng, i.lat]).addTo(this.map)
      this._overlays.push(marker)
    })
  }
  clearOverlays() { this._overlays.forEach(m => m.remove()); this._overlays = [] }
  destroy() { this.clearOverlays(); this.map.remove(); this.map = null }
}

// Waze overlay adapter — consumes incident feeds and renders over a base adapter
export class WazeOverlayAdapter {
  constructor(baseAdapter) { this.base = baseAdapter; this._currentData = [] }
  async init(container, opts) { /* no-op, baseAdapter already initialized*/ }
  async refreshFromFeed(feedFetcher) {
    // feedFetcher must return an array of incidents
    const data = await feedFetcher()
    this._currentData = data
    if (this.base) this.base.addIncidentOverlay(data)
  }
  clear() { if (this.base) this.base.clearOverlays(); this._currentData = [] }
  attachTo(baseAdapter) { this.base = baseAdapter; if (this._currentData.length) this.base.addIncidentOverlay(this._currentData) }
}

Runtime Switching: Replace the Adapter Without Rebuilding UI

The component that renders the UI should talk only to the adapter interface. To switch providers at runtime:

Call currentAdapter.destroy()
Instantiate and init the new adapter
If you have overlays (Waze), reattach them to the new adapter

// usage-example.js
import { GoogleAdapter, MapLibreAdapter, WazeOverlayAdapter } from './map-adapters.js'

const container = document.getElementById('map')
let activeAdapter = null
const wazeOverlay = new WazeOverlayAdapter(null)

async function switchToGoogle() {
  if (activeAdapter) activeAdapter.destroy()
  activeAdapter = new GoogleAdapter('YOUR_GOOGLE_API_KEY')
  await activeAdapter.init(container, { center: { lat: 37.7749, lng: -122.4194 }, zoom: 12 })
  wazeOverlay.attachTo(activeAdapter)
}

async function switchToOpen() {
  if (activeAdapter) activeAdapter.destroy()
  activeAdapter = new MapLibreAdapter('https://demotiles.maplibre.org/style.json')
  await activeAdapter.init(container, { center: { lat: 37.7749, lng: -122.4194 }, zoom: 12 })
  wazeOverlay.attachTo(activeAdapter)
}

// sample fetcher for Waze-like incidents (replace with real fetcher)
async function fetchDummyIncidents() {
  return [ { id: 1, lat: 37.78, lng: -122.42, type: 'accident', severity: 2 } ]
}

// periodically poll incident feed and refresh overlay
setInterval(async () => { await wazeOverlay.refreshFromFeed(fetchDummyIncidents) }, 5000)

// initial provider
switchToOpen()

Handling Gaps: When a Provider Only Supplies Overlays

In many procurement setups Waze supplies only incident feeds via partnership programs, not a full map renderer. The solution is to treat Waze as an overlay-only adapter and pair it with any base adapter (Google or MapLibre). The Waze overlay adapter should:

Fetch incidents respecting rate limits and licensing
Map incident geometries to screen coordinates of the underlying map SDK
Support filtering, deduplication, and severity visualization

Integration Tips for React / Vue

Keep the adapter instance in a ref or component property and avoid re-rendering the DOM node used by the provider SDK.

React (hooks)

function MapWrapper({provider}){
  const ref = useRef(null)
  const adapterRef = useRef(null)

  useEffect(() => {
    async function init(){
      if (adapterRef.current) { adapterRef.current.destroy() }
      if (provider === 'google') {
        adapterRef.current = new GoogleAdapter(process.env.REACT_APP_GOOGLE_KEY)
      } else {
        adapterRef.current = new MapLibreAdapter()
      }
      await adapterRef.current.init(ref.current, { center: { lat:0, lng:0 }, zoom:2 })
    }
    init()
    return () => adapterRef.current?.destroy()
  }, [provider])

  return 
}

Performance and UX Tradeoffs

Choose base and overlay providers based on these considerations:

Latency: Vector tiles + client styling reduce network bytes but increase initial JS cost. Use HTTP/2 and CDN edge caching for tiles.
Rendering: WebGL (maplibre, vector) uses GPU and scales well for many features; raster tiles are simpler for low-power devices.
Overlay Complexity: Overlay-heavy UIs (live incidents) benefit from lightweight markers or canvas layers to avoid DOM bloat.
Offline or Private Hosting: PMTiles and self-hosted tile servers let you host map tiles within corporate networks; consider edge-enabled hosting for some workloads.

Security and Privacy Notes (2026)

Always use HTTPS for tile and API calls.
Consider routing traffic through your backend if terms or privacy require server-side token management — especially for Waze feeds and Google API keys.
Audit third‑party SDKs for supply chain risks. In 2025 the community emphasized supply chain scanning and SCA in CI; include SCA in CI.

Licensing Cheat‑Sheet (Concise, Practical)

Licensing is the main reason teams need runtime switching. These are practical notes as of early 2026. Always consult the provider's current Terms of Service and your legal team before shipping.

Google Maps Platform
- Commercial, pay-as-you-go. Pricing changed significantly over 2020–2024 and remains important to model.
- Google requires you to use their SDKs and often enforces display/access restrictions — check the Maps Platform Terms for caching and tile usage limits.
Waze
- Waze incident feeds are typically provided via Waze for Cities / commercial partnerships. Data access is contractually controlled and often limited to specific applications.
- You usually cannot redistribute raw Waze data outside the permitted channels; plan for server-side mediation or display-only overlays per contract.
OpenStreetMap / MapLibre / PMTiles
- OpenStreetMap data is subject to the ODbL. Attribution is required; derived tile datasets may have share-alike implications.
- MapLibre and client libs are community-driven and generally permissive, but verify the exact license of the version you use.
Commercial Tile Providers (Mapbox, HERE, MapTiler, etc.)
- These offer enterprise SLAs and usage-based pricing; terms differ on caching, vector/style usage, and offline hosting.

For procurement: request sample contract language about data ownership, caching rights, and allowed display contexts. Insist on a pilot to measure cost per monthly active map user.

Decision Checklist — Should You Use Google, Waze, or Open Tiles?

Use this checklist when evaluating providers for a project in 2026.

Do you need live incident feeds (crowdsourced Waze-style)? If yes, pursue a Waze partnership or commercial feed and overlay it on any base map.
Is predictable SLAs and enterprise support required? If yes, prefer commercial providers (Google/HERE/Mapbox enterprise tiers).
Are cost and vendor lock-in top concerns? If yes, design for MapLibre + OSM/PMTiles + edge caching.
Do you need heavy client-side styling (theming, dynamic layers)? Vector tiles (MapLibre/Mapbox) are better than plain raster tiles.
Will your legal team permit storing or re-serving provider tiles? If not, plan server-side tile proxying with agreement from the provider.

Real-World Example: Massive Fleet UI Case Study (Summary)

A delivery platform we advised in 2025 reworked its mapping stack to an adapter model. Results in the first quarter after the change:

Time-to-integrate new tile providers dropped from 6 weeks to 2 days.
Switching from a commercial tile provider to a self-hosted PMTiles cache reduced monthly tile bill by ~60% (device-level telemetry allowed tighter caching policies).
Legal approvals for Waze overlays took longer than engineering work — the adapter model let engineers proceed in parallel while contracts completed.

Advanced Strategies and 2026 Predictions

Looking forward, expect these trends to shape architectural choices:

Edge-deployed vector tile caches (PMTiles + CDN) will make open stacks competitive for latency-sensitive apps — see work on edge-first delivery.
Overlay streaming — incident feeds delivered as WebSocket/Server-Sent Events with delta updates for ultra-low-latency overlays.
Composable SDKs — smaller, composable mapping primitives that let teams pick rendering, routing, and incident layers independently.

Checklist: What To Deliver With Your Component

To ship a reusable mapping component internally or as a commercial module, include:

Adapter interface docs and example adapters (Google, MapLibre, Waze overlay)
Demo page and sandbox with toggles to switch providers at runtime
License summary and sample contract clauses for legal review
Performance baseline (tile latency, memory usage, overlay render time) and test script
Migration guide for customers moving away from a single provider

Practical Takeaways

Decouple UI from provider SDKs — use an adapter interface early in the design.
Treat Waze as an overlay-only data source unless your contract includes full-service SDKs. For overlay streaming and feeds, review the trend reports on live streams.
Prefer vector tiles + MapLibre for theming and cost control, but profile GPU usage on target devices.
Keep legal and procurement in the loop — licensing often determines architectural choices faster than engineering preferences. Consider privacy guidance from programmatic privacy reviews.

Next Steps — Starter Repo and Pilot Checklist

If you want to implement this pattern in your codebase, start with these three steps:

Clone a minimal adapter repo (MapLibre + Google + Waze overlay examples).
Run a 2-week pilot: measure tile costs with representative traffic, test overlay latency at peak load.
Validate contract terms for any third-party feed (Waze) or tile provider before going to production.

Call to Action

Ready to stop rewriting maps for every project? Download the starter adapter repo, run the demo, and use the included procurement checklist to brief legal and product. If you’d rather get a tailored evaluation, contact our team for a 2-week architecture pilot: we’ll map your tile costs, integration risk, and run a provider-switch proof-of-concept that uses your actual incident feeds.

Try the demo, measure the costs, and keep your UI portable.

javascripts

Contributor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.