fix(google-maps): re-init on color-mode change for cloud-styled mapIds

docs/content/scripts/google-maps/1.guides/2.map-styling.md

@@ -84,6 +84,22 @@ Switch map styles automatically based on the user's color mode preference. Provi
 </template>
 ```
 
+If you set up a single Map ID in Google Cloud Console with both Light and Dark color schemes, point both keys at the same id and the map will pick up Google's `colorScheme` automatically:
+
+```vue
+<template>
+ <ScriptGoogleMaps
+ :map-ids="{ light: 'YOUR_MAP_ID', dark: 'YOUR_MAP_ID' }"
+ :center="{ lat: -33.8688, lng: 151.2093 }"
+ :zoom="12"
+ />
+</template>
+```
+
+::callout{color="amber"}
+Google Maps treats both `mapId` and `colorScheme` as init-only options. Toggling color mode tears down and re-creates the basic `Map` instance (preserving the user's pan/zoom). Child components (markers, info windows, overlays) are remounted against the new map automatically.
+::
+
 This auto-detects `@nuxtjs/color-mode` if installed. You can also control it manually with the `colorMode` prop:
 
 ```vue

packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue

@@ -155,7 +155,7 @@ import { useScriptGoogleMaps } from '#nuxt-scripts/registry/google-maps'
 import { scriptRuntimeConfig, scriptsPrefix } from '#nuxt-scripts/utils'
 import { defu } from 'defu'
 import { tryUseNuxtApp, useHead, useRuntimeConfig } from 'nuxt/app'
-import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, useAttrs, useTemplateRef, watch } from 'vue'
+import { computed, nextTick, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, useAttrs, useTemplateRef, watch } from 'vue'
 import ScriptAriaLoadingIndicator from '../ScriptAriaLoadingIndicator.vue'
 import { defineDeprecatedAlias, MAP_INJECTION_KEY, waitForMapsReady, warnDeprecatedTopLevelMapProps } from './useGoogleMapsResource'
 
@@ -186,6 +186,16 @@ const currentMapId = computed(() => {
  return props.mapIds[currentColorMode.value] || props.mapIds.light || props.mapOptions?.mapId
 })
 
+// `colorScheme` is a Google Maps init-only option that drives Cloud-based
+// styling for a single mapId. We always derive it so that toggling color mode
+// triggers a re-init even when the resolved mapId is unchanged (e.g. a single
+// mapId hosting both Light/Dark cloud themes).
+const currentColorScheme = computed<google.maps.ColorScheme | undefined>(() => {
+ if (!props.mapIds && !props.colorMode && !nuxtColorMode.value)
+ return undefined
+ return currentColorMode.value === 'dark' ? 'DARK' as google.maps.ColorScheme : 'LIGHT' as google.maps.ColorScheme
+})
+
 const mapsApi = shallowRef<typeof google.maps | undefined>()
 
 if (import.meta.dev) {
@@ -229,13 +239,19 @@ const options = computed(() => {
  // are mounted against a styled (mapId-less) map.
  const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'DEMO_MAP_ID')
  return defu(
- { center: centerOverride.value, mapId },
+ { center: centerOverride.value, mapId, colorScheme: currentColorScheme.value },
  props.mapOptions,
  { center: props.center, zoom: props.zoom },
  { zoom: 15 },
  )
 })
 const isMapReady = ref(false)
+// Drives default-slot mounting. Starts true so children mount immediately
+// (preserving v0/v1 behavior where children wait for map readiness via
+// `useGoogleMapsResource`). Toggled false→true when the map is re-initialized
+// (mapId or colorScheme change) so child components remount and re-run their
+// `whenever({ once: true })` create callbacks against the new map instance.
+const slotMounted = ref(true)
 
 const map: ShallowRef<google.maps.Map | undefined> = shallowRef()
 
@@ -375,9 +391,44 @@ onMounted(() => {
  return
  // Exclude center and zoom — they have dedicated watchers that avoid
  // resetting user interactions (pan/zoom) on unrelated re-renders.
- const { center: _, zoom: __, ...rest } = options.value
+ // Exclude mapId and colorScheme — Google Maps treats these as init-only;
+ // changes are handled by the dedicated re-init watcher below.
+ const { center: _, zoom: __, mapId: ___, colorScheme: ____, ...rest } = options.value
  map.value.setOptions(rest)
  })
+ // Re-init map when mapId or colorScheme changes (e.g. user toggles color mode
+ // with `mapIds` set or with cloud-based styling on a single mapId). Both are
+ // init-only in Google Maps; setOptions is a no-op + dev warning. We tear
+ // down and recreate the map preserving the user's pan/zoom state, and
+ // toggle `slotMounted` so child components remount and re-bind to the new
+ // map instance via their `whenever({ once: true })` create callbacks.
+ watch([currentMapId, currentColorScheme], async ([newMapId, newScheme], [oldMapId, oldScheme]) => {
+ if (!map.value || !mapsApi.value || !mapEl.value)
+ return
+ if (newMapId === oldMapId && newScheme === oldScheme)
+ return
+ const center = map.value.getCenter()
+ const zoom = map.value.getZoom()
+ map.value.unbindAll()
+ map.value = undefined
+ slotMounted.value = false
+ // Clear any DOM children left by the previous Map instance — Google Maps
+ // expects to render into an empty container.
+ if (mapEl.value)
+ mapEl.value.innerHTML = ''
+ await nextTick()
+ // Component may have unmounted (or refs been torn down) during nextTick;
+ // bail out so we don't spin up a Map against a detached container.
+ if (!mapEl.value || !mapsApi.value)
+ return
+ const _options: google.maps.MapOptions = {
+ ...options.value,
+ center: center ? { lat: center.lat(), lng: center.lng() } : options.value.center,
+ zoom: zoom ?? options.value.zoom,
+ }
+ map.value = new mapsApi.value.Map(mapEl.value, _options)
+ slotMounted.value = true
+ })
  watch(() => options.value.zoom, (zoom) => {
  if (map.value && zoom != null)
  map.value.setZoom(zoom)
@@ -497,6 +548,6 @@ onBeforeUnmount(() => {
  </slot>
  <slot v-if="status === 'awaitingLoad'" name="awaitingLoad" />
  <slot v-else-if="status === 'error'" name="error" />
- <slot />
+ <slot v-if="slotMounted" />
  </div>
 </template>

test/unit/google-maps-regressions.test.ts

@@ -329,9 +329,11 @@ describe('google Maps Regressions', () => {
  map.setOptions(options)
  }
 
- // Simulate the fixed watcher: strips center and zoom before calling setOptions
+ // Simulate the fixed watcher: strips center, zoom, mapId, and colorScheme
+ // before calling setOptions. mapId/colorScheme are init-only in Google Maps
+ // and are handled by a dedicated re-init watcher (see #726 regression suite).
  function applyOptionsFixed(map: ReturnType<typeof createMockMap>, options: Record<string, any>) {
- const { center: _, zoom: __, ...rest } = options
+ const { center: _, zoom: __, mapId: ___, colorScheme: ____, ...rest } = options
  map.setOptions(rest)
  }
 
@@ -348,19 +350,22 @@ describe('google Maps Regressions', () => {
  )
  })
 
- it('fixed behavior: setOptions excludes zoomand center', () => {
+ it('fixed behavior: setOptions excludes zoom, center, mapId, and colorScheme', () => {
  const map = createMockMap()
- const options = { center: { lat: 40, lng: -74 }, zoom: 12, mapId: 'abc' }
+ const options = { center: { lat: 40, lng: -74 }, zoom: 12, mapId: 'abc', disableDefaultUI: true }
 
  applyOptionsFixed(map, options)
 
- expect(map.setOptions).toHaveBeenCalledWith({ mapId: 'abc' })
+ expect(map.setOptions).toHaveBeenCalledWith({ disableDefaultUI: true })
  expect(map.setOptions).not.toHaveBeenCalledWith(
  expect.objectContaining({ center: expect.anything() }),
  )
  expect(map.setOptions).not.toHaveBeenCalledWith(
  expect.objectContaining({ zoom: expect.anything() }),
  )
+ expect(map.setOptions).not.toHaveBeenCalledWith(
+ expect.objectContaining({ mapId: expect.anything() }),
+ )
  })
 
  it('old behavior: repeated overlay toggles reset zoom/center every time', () => {
@@ -502,4 +507,118 @@ describe('google Maps Regressions', () => {
  expect(iw.close).not.toHaveBeenCalled()
  })
  })
+
+ describe('color-mode reactivity for cloud-based map IDs (#726)', () => {
+ // Regression: toggling color mode with `mapIds` set (or with cloud-based
+ // styling on a single mapId) did not update the map. The old code passed
+ // the resolved mapId via `setOptions`, which Google Maps refuses
+ // ("A Map's mapId property cannot be changed after initial Map render").
+ // Both `mapId` and `colorScheme` are init-only; the fix excludes them
+ // from the generic setOptions call and re-initialises the Map instance
+ // when either changes.
+
+ function resolveMapId(props: {
+ mapIds?: { light?: string, dark?: string }
+ mapOptions?: { mapId?: string }
+ }, colorMode: 'light' | 'dark') {
+ if (!props.mapIds)
+ return props.mapOptions?.mapId
+ return props.mapIds[colorMode] || props.mapIds.light || props.mapOptions?.mapId
+ }
+
+ function resolveColorScheme(props: {
+ mapIds?: { light?: string, dark?: string }
+ colorMode?: 'light' | 'dark'
+ hasNuxtColorMode?: boolean
+ }, currentColorMode: 'light' | 'dark') {
+ if (!props.mapIds && !props.colorMode && !props.hasNuxtColorMode)
+ return undefined
+ return currentColorMode === 'dark' ? 'DARK' : 'LIGHT'
+ }
+
+ function applyOptionsFixed(map: ReturnType<typeof createMockMap>, options: Record<string, any>) {
+ const { center: _, zoom: __, mapId: ___, colorScheme: ____, ...rest } = options
+ map.setOptions(rest)
+ }
+
+ it('strips mapId and colorScheme from setOptions to avoid the init-only warning', () => {
+ const map = createMockMap()
+ const options = {
+ center: { lat: 40, lng: -74 },
+ zoom: 12,
+ mapId: 'abc',
+ colorScheme: 'DARK',
+ disableDefaultUI: true,
+ }
+
+ applyOptionsFixed(map, options)
+
+ expect(map.setOptions).toHaveBeenCalledWith({ disableDefaultUI: true })
+ expect(map.setOptions).not.toHaveBeenCalledWith(
+ expect.objectContaining({ mapId: expect.anything() }),
+ )
+ expect(map.setOptions).not.toHaveBeenCalledWith(
+ expect.objectContaining({ colorScheme: expect.anything() }),
+ )
+ })
+
+ it('resolves a different mapId per color mode when both light and dark are provided', () => {
+ const props = { mapIds: { light: 'LIGHT_ID', dark: 'DARK_ID' } }
+
+ expect(resolveMapId(props, 'light')).toBe('LIGHT_ID')
+ expect(resolveMapId(props, 'dark')).toBe('DARK_ID')
+ })
+
+ it('emits a colorScheme so a single mapId with cloud-based light/dark styling can re-init', () => {
+ // User configured one mapId in Cloud Console with both Light and Dark
+ // schemes. mapIds resolves to the same id in both modes, so the only
+ // signal that triggers re-init is the colorScheme value.
+ const props = { mapIds: { light: 'SAME_ID', dark: 'SAME_ID' } }
+
+ expect(resolveMapId(props, 'light')).toBe('SAME_ID')
+ expect(resolveMapId(props, 'dark')).toBe('SAME_ID')
+
+ expect(resolveColorScheme(props, 'light')).toBe('LIGHT')
+ expect(resolveColorScheme(props, 'dark')).toBe('DARK')
+ })
+
+ it('does not emit a colorScheme when no color-mode props or @nuxtjs/color-mode are present', () => {
+ // Avoid forcing a LIGHT scheme on existing maps that never opted in to
+ // color-mode reactivity — would otherwise needlessly re-init on first
+ // mount or accidentally override mapOptions.colorScheme.
+ expect(resolveColorScheme({}, 'light')).toBeUndefined()
+ })
+
+ it('emits a colorScheme when @nuxtjs/color-mode is detected even without explicit mapIds', () => {
+ expect(resolveColorScheme({ hasNuxtColorMode: true }, 'dark')).toBe('DARK')
+ })
+
+ it('triggers re-init only when the resolved mapId or colorScheme actually changes', () => {
+ // Mirrors the dedup guard in the recreate watcher.
+ function shouldReinit(
+ prev: { mapId: string | undefined, scheme: string | undefined },
+ next: { mapId: string | undefined, scheme: string | undefined },
+ ) {
+ return prev.mapId !== next.mapId || prev.scheme !== next.scheme
+ }
+
+ // Identical → no re-init (covers e.g. unrelated re-renders that re-evaluate the options computed).
+ expect(shouldReinit(
+ { mapId: 'abc', scheme: 'LIGHT' },
+ { mapId: 'abc', scheme: 'LIGHT' },
+ )).toBe(false)
+
+ // mapId changes (two-id light/dark setup).
+ expect(shouldReinit(
+ { mapId: 'LIGHT_ID', scheme: 'LIGHT' },
+ { mapId: 'DARK_ID', scheme: 'DARK' },
+ )).toBe(true)
+
+ // Single mapId, only colorScheme changes (cloud styling on one id).
+ expect(shouldReinit(
+ { mapId: 'SAME_ID', scheme: 'LIGHT' },
+ { mapId: 'SAME_ID', scheme: 'DARK' },
+ )).toBe(true)
+ })
+ })
 })