| name | google-maps-js-2d |
| description | Use for focused Google Maps JavaScript API 2D map work in either app, including API loading, map IDs/vector maps, camera, controls, Advanced Markers, info windows, data-driven styling, GeoJSON/Data layer, deck.gl overlays, WebGLOverlayView, Places widgets, geocoding, performance, accessibility, quota, security, and migration from Mapbox GL to Google Maps JS. |
Google Maps JavaScript API 2D
Use this repo-local skill when a task changes 2D Google Maps rendering, map loading, markers, overlays, controls, Places/geocoding widgets, or a Mapbox-to-Google Maps migration path in demos/aqi-map/ or demos/strava-explorer/.
Quick workflow
- Identify the target app and runtime before editing:
demos/aqi-map/ is a Vite app using Google Maps Platform Air Quality API heatmap tiles.demos/strava-explorer/ is a Vite app with centralized Google Maps Platform loading in demos/strava-explorer/src/gmp.js.
- Read the app's
package.json, README, relevant HTML, and map source files before changing map code.
- Verify current Maps JavaScript API behavior against official docs when touching loader, library imports, Advanced Markers, data-driven styling, WebGL, deck.gl, Drawing/Heatmap replacements, or release channels.
- Keep Maps JavaScript API loading centralized. Do not add duplicate script tags, duplicate
Loader instances, or parallel loader mechanisms.
- Prefer
google.maps.importLibrary() after the Maps JavaScript API loader has resolved:
maps for Map, InfoWindow, controls, and core camera.marker for AdvancedMarkerElement and PinElement.places for Places widgets and services.geocoding, geometry, or other libraries only when needed.
- Validate latitude/longitude ranges before rendering, sending requests, or building tile URLs.
- For visible map/UI changes, run a build plus browser/screenshot QA when the environment allows it.
Official references to check
2D implementation rules
- Prefer vector maps with a map ID for new Google Maps JS work so cloud styling, tilt/heading, Advanced Markers, and data-driven styling options remain available.
- Prefer
AdvancedMarkerElement over legacy google.maps.Marker for new markers.
- Use semantic, accessible marker content for interactive markers. Include an accessible label/title and keyboard-operable details where practical. Keep custom marker DOM lightweight and verify console warnings after API changes.
- Use
InfoWindow for simple details and a custom overlay, Advanced Marker content, or app-side panel for richer interactive UI.
- Prefer official Places widgets/services for search/autocomplete instead of hand-rolled geocoder UX.
- Avoid the Maps JavaScript API Heatmap Layer and Drawing Library for new work: Google deprecated Heatmap Layer in May 2025 and made it unavailable in May 2026; Drawing Library was deprecated in August 2025 and unavailable in May 2026. Prefer deck.gl heatmaps, custom WebGL/canvas overlays, or server-generated tiles for heatmaps; use custom drawing tools or Data layer/editing alternatives for drawing.
- Use deck.gl
GoogleMapsOverlay for large point clouds, heatmaps, contours, or animated geospatial visualizations that exceed practical DOM marker counts.
- Use
Data layer/GeoJSON for small-to-moderate feature collections and simple styling; use deck.gl or tiled/vector data for large or frequently changing datasets.
- Batch, debounce, or cache quota-sensitive service calls such as Geocoding, Places, Routes, Environment APIs, and Elevation.
- Keep map container CSS scoped. Avoid global CSS that affects Google-rendered controls or shadow DOM descendants unexpectedly.
- Respect
prefers-reduced-motion for camera animations, auto-pan, flyovers, or continuous viewport changes.
Mapbox GL to Google Maps JS migration notes for demos/aqi-map/
When migrating demos/aqi-map/ from Mapbox GL to Google Maps JS:
- Preserve the existing product behavior first: global AQI map, geocoder/search, clustered sensors, AQI color ramp, sensor popups, contours/isobands, mobile panel, and PurpleAir attribution.
- Replace Mapbox token/style configuration with documented Google Maps Platform browser API-key configuration. Do not commit real keys.
- Replace Mapbox Geocoder with Places Autocomplete or Place Autocomplete Element where appropriate.
- Replace Mapbox clustering with one of:
@googlemaps/markerclusterer plus Advanced Markers for marker-based clustering.- deck.gl aggregation layers for dense AQI visualization.
- Server/precomputed vector tiles for very large datasets.
- Replace Mapbox fill/circle/symbol layers with Google Maps Data layer, deck.gl layers, or custom overlays depending on feature count and styling needs.
- Replace Mapbox globe/projection requirements with Google Maps vector map capabilities; confirm any 3D/globe requirement separately with the 3D skill.
- Revisit all API keys/tokens and document required API restrictions, HTTP referrers, local development origins, and enabled APIs.
QA checklist
- Map loads exactly once and no duplicate billing/loading paths are introduced.
- Browser API key restrictions and enabled APIs are documented.
- Search/geocoding has accessible labels and clear loading/error states.
- Marker/detail content is keyboard-accessible where practical.
- Large datasets avoid thousands of DOM markers unless clustered/windowed.
- Tile, API, and service requests are bounded by viewport, zoom, cache, or debounce logic.
- Mobile controls do not cover essential map controls or trap gestures.
- Build command passes from the app directory.
