From 9d15300991245581feb550e33908be76236b6232 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 17 Apr 2026 11:29:52 +1000
Subject: [PATCH 1/3] fix(google-maps): allow map styling guide to work with
 markers

Closes #716

JSON `mapOptions.styles` previously dropped `mapId`, breaking
`AdvancedMarkerElement` which v1 `ScriptGoogleMapsMarker` requires.
Always pass `mapId` through; add a dev warning when `styles` is set
pointing users to cloud-based styling.
---
 .../google-maps/1.guides/2.map-styling.md       | 10 +++++++---
 .../components/GoogleMaps/ScriptGoogleMaps.vue  | 17 +++++++++++------
 2 files changed, 18 insertions(+), 9 deletions(-)

diff --git a/docs/content/scripts/google-maps/1.guides/2.map-styling.md b/docs/content/scripts/google-maps/1.guides/2.map-styling.md
index 0cbecdf2a..ca878264c 100644
--- a/docs/content/scripts/google-maps/1.guides/2.map-styling.md
+++ b/docs/content/scripts/google-maps/1.guides/2.map-styling.md
@@ -2,13 +2,17 @@
 title: Map Styling
 ---
 
-Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Both work with Nuxt Scripts, including the static map placeholder.
+Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Cloud-based map IDs are the recommended approach for v1 and work with `ScriptGoogleMapsMarker`.
 
 ## JSON Styles
 
+::callout{color="amber"}
+JSON `styles` conflict with `ScriptGoogleMapsMarker` in v1. `AdvancedMarkerElement` requires a `mapId`, and Google Maps ignores `styles` when a `mapId` is present. If you need markers, use [cloud-based map IDs](#cloud-based-map-ids) instead.
+::
+
 Use the `mapOptions.styles` prop with a JSON style array. You can find pre-made styles on [Snazzy Maps](https://snazzymaps.com/).
 
-Styles automatically apply to both the static map placeholder and the interactive map.
+Styles apply to the static map placeholder and to the interactive map when the map has no markers.
 
 ```vue
 <script setup lang="ts">
@@ -63,7 +67,7 @@ Google's [Map Styling](https://developers.google.com/maps/documentation/cloud-cu
 ```
 
 ::callout{color="amber"}
-JSON `styles` and `mapId` are mutually exclusive. When you provide both, the component ignores `mapId` and applies `styles`. Note that `AdvancedMarkerElement` requires a map ID to function; legacy `Marker` works without one.
+JSON `styles` and `mapId` are mutually exclusive. When both are set, Google Maps keeps `mapId` and ignores `styles`. Because v1's `ScriptGoogleMapsMarker` uses `AdvancedMarkerElement` (which requires a `mapId`), cloud-based map IDs are the only way to style a map that contains markers.
 ::
 
 ## Dark Mode / Color Mode
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
index b3fabf9e5..a99ce80a5 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
@@ -223,12 +223,9 @@ const { load, status, onLoaded } = useScriptGoogleMaps({
 })
 
 const options = computed(() => {
-  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'map')
-  // Precedence (defu merges left-to-right, leftmost wins):
-  // 1. centerOverride: resolved query result, always wins for center
-  // 2. mapOptions: preferred public API
-  // 3. deprecated top-level: legacy fallback for center/zoom
-  // 4. defaults: { zoom: 15 } when nothing else is set
+  // v1 markers use AdvancedMarkerElement which requires a mapId, so we always pass one.
+  // Google will ignore JSON `styles` when `mapId` is set — we warn below in dev.
+  const mapId = currentMapId.value || 'map'
   return defu(
     { center: centerOverride.value, mapId },
     props.mapOptions,
@@ -236,6 +233,14 @@ const options = computed(() => {
     { zoom: 15 },
   )
 })
+
+if (import.meta.dev) {
+  watch(() => props.mapOptions?.styles, (styles) => {
+    if (styles) {
+      console.warn('[nuxt-scripts] <ScriptGoogleMaps> `mapOptions.styles` (JSON styles) is incompatible with `ScriptGoogleMapsMarker` in v1, which requires a `mapId` for `AdvancedMarkerElement`. Google Maps will ignore `styles` when `mapId` is set. Use cloud-based map styling instead: https://scripts.nuxt.com/scripts/google-maps/guides/map-styling')
+    }
+  }, { immediate: true })
+}
 const isMapReady = ref(false)
 
 const map: ShallowRef<google.maps.Map | undefined> = shallowRef()

From dfba95e8529c9fa1b118fecc1c45a85943d09178 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 17 Apr 2026 11:38:59 +1000
Subject: [PATCH 2/3] refactor(google-maps): move styles/mapId conflict warning
 to marker

Preserve JSON styles for maps without markers (no regression for
styles-only users). Warn at the marker, where the conflict actually
surfaces, when the parent map has no mapId. Update the styling guide
to state the conflict is between styles and markers.
---
 .../google-maps/1.guides/2.map-styling.md        | 14 +++++++-------
 .../components/GoogleMaps/ScriptGoogleMaps.vue   | 16 +++++-----------
 .../GoogleMaps/ScriptGoogleMapsMarker.vue        |  3 +++
 3 files changed, 15 insertions(+), 18 deletions(-)

diff --git a/docs/content/scripts/google-maps/1.guides/2.map-styling.md b/docs/content/scripts/google-maps/1.guides/2.map-styling.md
index ca878264c..80ea71de3 100644
--- a/docs/content/scripts/google-maps/1.guides/2.map-styling.md
+++ b/docs/content/scripts/google-maps/1.guides/2.map-styling.md
@@ -2,17 +2,17 @@
 title: Map Styling
 ---
 
-Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Cloud-based map IDs are the recommended approach for v1 and work with `ScriptGoogleMapsMarker`.
+Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Both work with Nuxt Scripts, including the static map placeholder.
 
 ## JSON Styles
 
-::callout{color="amber"}
-JSON `styles` conflict with `ScriptGoogleMapsMarker` in v1. `AdvancedMarkerElement` requires a `mapId`, and Google Maps ignores `styles` when a `mapId` is present. If you need markers, use [cloud-based map IDs](#cloud-based-map-ids) instead.
-::
-
 Use the `mapOptions.styles` prop with a JSON style array. You can find pre-made styles on [Snazzy Maps](https://snazzymaps.com/).
 
-Styles apply to the static map placeholder and to the interactive map when the map has no markers.
+Styles apply to both the static map placeholder and the interactive map.
+
+::callout{color="amber"}
+JSON `styles` cannot combine with `ScriptGoogleMapsMarker`. `AdvancedMarkerElement` requires a `mapId`, and Google Maps treats `styles` and `mapId` as mutually exclusive. If the map contains markers, use [cloud-based map IDs](#cloud-based-map-ids) instead.
+::
 
 ```vue
 <script setup lang="ts">
@@ -67,7 +67,7 @@ Google's [Map Styling](https://developers.google.com/maps/documentation/cloud-cu
 ```
 
 ::callout{color="amber"}
-JSON `styles` and `mapId` are mutually exclusive. When both are set, Google Maps keeps `mapId` and ignores `styles`. Because v1's `ScriptGoogleMapsMarker` uses `AdvancedMarkerElement` (which requires a `mapId`), cloud-based map IDs are the only way to style a map that contains markers.
+JSON `styles` and `mapId` are mutually exclusive. When both are set, Google Maps keeps `mapId` and ignores `styles`. Because `ScriptGoogleMapsMarker` uses `AdvancedMarkerElement` (which requires a `mapId`), cloud-based map IDs are the only way to style a map that contains markers.
 ::
 
 ## Dark Mode / Color Mode
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
index a99ce80a5..03303a422 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
@@ -223,9 +223,11 @@ const { load, status, onLoaded } = useScriptGoogleMaps({
 })
 
 const options = computed(() => {
-  // v1 markers use AdvancedMarkerElement which requires a mapId, so we always pass one.
-  // Google will ignore JSON `styles` when `mapId` is set — we warn below in dev.
-  const mapId = currentMapId.value || 'map'
+  // JSON `styles` and `mapId` are mutually exclusive in Google Maps. When the user
+  // sets `styles`, we drop `mapId` so styles apply. Otherwise fall back to a map ID
+  // so `AdvancedMarkerElement` can function. The marker component warns if markers
+  // are mounted against a styled (mapId-less) map.
+  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'map')
   return defu(
     { center: centerOverride.value, mapId },
     props.mapOptions,
@@ -233,14 +235,6 @@ const options = computed(() => {
     { zoom: 15 },
   )
 })
-
-if (import.meta.dev) {
-  watch(() => props.mapOptions?.styles, (styles) => {
-    if (styles) {
-      console.warn('[nuxt-scripts] <ScriptGoogleMaps> `mapOptions.styles` (JSON styles) is incompatible with `ScriptGoogleMapsMarker` in v1, which requires a `mapId` for `AdvancedMarkerElement`. Google Maps will ignore `styles` when `mapId` is set. Use cloud-based map styling instead: https://scripts.nuxt.com/scripts/google-maps/guides/map-styling')
-    }
-  }, { immediate: true })
-}
 const isMapReady = ref(false)
 
 const map: ShallowRef<google.maps.Map | undefined> = shallowRef()
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue
index 5b2a982f5..c35586c21 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue
@@ -57,6 +57,9 @@ let gmpClickHandler: ((e: any) => void) | undefined
 const advancedMarkerElement = useGoogleMapsResource<google.maps.marker.AdvancedMarkerElement>({
   ready: () => !slots.content || !!markerContent.value,
   async create({ mapsApi, map }) {
+    if (import.meta.dev && !map.get('mapId')) {
+      console.warn('[nuxt-scripts] <ScriptGoogleMapsMarker> requires the parent <ScriptGoogleMaps> to have a `mapId` set, but none was found. This usually happens when `mapOptions.styles` (JSON styles) is set, since Google Maps treats `styles` and `mapId` as mutually exclusive. Use cloud-based map styling instead: https://scripts.nuxt.com/scripts/google-maps/guides/map-styling')
+    }
     await mapsApi.importLibrary('marker')
     const marker = new mapsApi.marker.AdvancedMarkerElement({
       ...props.options,

From ca9969377a131f54bbc8179726bade8bbef78956 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Fri, 17 Apr 2026 11:54:13 +1000
Subject: [PATCH 3/3] fix(google-maps): default mapId fallback to DEMO_MAP_ID

Google's pre-registered dev map ID. An arbitrary string like 'map'
triggers a console warning every load; DEMO_MAP_ID renders silently
and matches Google's documented convention for examples.
---
 .../src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue      | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
index 03303a422..3d5572d3d 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
@@ -227,7 +227,7 @@ const options = computed(() => {
   // sets `styles`, we drop `mapId` so styles apply. Otherwise fall back to a map ID
   // so `AdvancedMarkerElement` can function. The marker component warns if markers
   // are mounted against a styled (mapId-less) map.
-  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'map')
+  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'DEMO_MAP_ID')
   return defu(
     { center: centerOverride.value, mapId },
     props.mapOptions,