From 32c6bbbcd47498cfc7a4d763794c9127d4e6944a Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 26 Mar 2026 15:02:34 +1100
Subject: [PATCH 1/4] feat!: extract static map into standalone
 ScriptGoogleMapsStaticMap component

BREAKING CHANGE: Remove `placeholderOptions`, `placeholderAttrs`, and `aboveTheFold` props from ScriptGoogleMaps. The built-in static map placeholder image is no longer rendered by default.

Use the new `ScriptGoogleMapsStaticMap` component in the `#placeholder` slot instead:

```vue
<ScriptGoogleMaps :center="center" :zoom="7">
  <template #placeholder>
    <ScriptGoogleMapsStaticMap :center="center" :zoom="7" loading="eager" />
  </template>
</ScriptGoogleMaps>
```

The new component can also be used standalone (store locators, contact pages, etc.) and fixes the percentage width/height bug that produced invalid Static Maps API `size` parameters by auto-measuring rendered dimensions on mount.
---
 .../GoogleMaps/ScriptGoogleMaps.vue           | 117 +-------
 .../GoogleMaps/ScriptGoogleMapsStaticMap.vue  | 258 ++++++++++++++++++
 .../third-parties/google-maps/center.vue      |   1 -
 .../third-parties/google-maps/emit-test.vue   |   1 -
 .../google-maps/geojson-test.vue              |   1 -
 .../third-parties/google-maps/markers.vue     |   1 -
 .../pages/third-parties/google-maps/null.vue  |   1 -
 .../google-maps/nuxt-scripts.vue              |  13 +-
 .../google-maps/overlay-animated.vue          |   1 -
 .../google-maps/overlay-popup.vue             |   1 -
 .../pages/third-parties/google-maps/query.vue |   1 -
 .../pages/third-parties/google-maps/sfcs.vue  |   1 -
 .../third-parties/google-maps/styled.vue      |   1 -
 13 files changed, 280 insertions(+), 118 deletions(-)
 create mode 100644 packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue

diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
index 9375e282..5ae0b7b2 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
@@ -1,14 +1,12 @@
 <script lang="ts">
 /// <reference types="google.maps" />
 import type { ElementScriptTrigger } from '#nuxt-scripts/types'
-import type { QueryObject } from 'ufo'
-import type { HTMLAttributes, ImgHTMLAttributes, ReservedProps, ShallowRef } from 'vue'
+import type { HTMLAttributes, ReservedProps, ShallowRef } from 'vue'
 import { useScriptTriggerElement } from '#nuxt-scripts/composables/useScriptTriggerElement'
 import { useScriptGoogleMaps } from '#nuxt-scripts/registry/google-maps'
 import { scriptRuntimeConfig } from '#nuxt-scripts/utils'
 import { defu } from 'defu'
 import { tryUseNuxtApp, useHead, useRuntimeConfig } from 'nuxt/app'
-import { withQuery } from 'ufo'
 import { computed, onBeforeUnmount, onMounted, provide, ref, shallowRef, toRaw, watch } from 'vue'
 import ScriptAriaLoadingIndicator from '../ScriptAriaLoadingIndicator.vue'
 
@@ -18,36 +16,11 @@ export { MAP_INJECTION_KEY } from './useGoogleMapsResource'
 </script>
 
 <script lang="ts" setup>
-export interface PlaceholderOptions {
-  width?: string | number
-  height?: string | number
-  center?: string
-  zoom?: number
-  size?: string
-  scale?: number
-  format?: 'png' | 'jpg' | 'gif' | 'png8' | 'png32' | 'jpg-baseline'
-  maptype?: 'roadmap' | 'satellite' | 'terrain' | 'hybrid'
-  language?: string
-  region?: string
-  markers?: string
-  path?: string
-  visible?: string
-  style?: string
-  map_id?: string
-  key?: string
-  signature?: string
-}
-
 const props = withDefaults(defineProps<{
   /**
    * Defines the trigger event to load the script.
    */
   trigger?: ElementScriptTrigger
-  /**
-   * Is Google Maps being rendered above the fold?
-   * This will load the placeholder image with higher priority.
-   */
-  aboveTheFold?: boolean
   /**
    * Defines the Google Maps API key. Must have access to the Static Maps API as well.
    */
@@ -85,16 +58,6 @@ const props = withDefaults(defineProps<{
    * Defines the height of the map
    */
   height?: number | string
-  /**
-   * Customize the placeholder image attributes.
-   *
-   * @see https://developers.google.com/maps/documentation/maps-static/start.
-   */
-  placeholderOptions?: PlaceholderOptions
-  /**
-   * Customize the placeholder image attributes.
-   */
-  placeholderAttrs?: ImgHTMLAttributes & ReservedProps & Record<string, unknown>
   /**
    * Customize the root element attributes.
    */
@@ -130,7 +93,6 @@ const emits = defineEmits<{
 
 const apiKey = props.apiKey || scriptRuntimeConfig('googleMaps')?.apiKey
 const runtimeConfig = useRuntimeConfig()
-const proxyConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
 
 // Color mode support - try to auto-detect from @nuxtjs/color-mode
 const nuxtApp = tryUseNuxtApp()
@@ -155,8 +117,6 @@ const mapsApi = ref<typeof google.maps | undefined>()
 if (import.meta.dev) {
   if (!apiKey)
     throw new Error('GoogleMaps requires an API key. Enable it in your nuxt.config:\n\n  scripts: {\n    registry: {\n      googleMaps: true\n    }\n  }\n\nThen set NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY in your .env file.\n\nAlternatively, pass `api-key` directly on the <ScriptGoogleMaps> component (note: this exposes the key client-side).')
-  if (!proxyConfig?.enabled && !props.apiKey)
-    console.warn('[nuxt-scripts] Google Maps proxy is not enabled. Enable `googleMaps` in your nuxt.config registry to keep your API key server-side. See: https://scripts.nuxt.com/scripts/google-maps#setup')
 }
 
 const rootEl = ref<HTMLElement>()
@@ -339,90 +299,37 @@ onMounted(() => {
   })
 })
 
-if (import.meta.server && !proxyConfig?.enabled) {
+if (import.meta.server) {
   useHead({
     link: [
       {
-        rel: props.aboveTheFold ? 'preconnect' : 'dns-prefetch',
+        rel: 'dns-prefetch',
         href: 'https://maps.googleapis.com',
       },
     ],
   })
 }
 
-function transformMapStyles(styles: google.maps.MapTypeStyle[]) {
-  return styles.map((style) => {
-    const feature = style.featureType ? `feature:${style.featureType}` : ''
-    const element = style.elementType ? `element:${style.elementType}` : ''
-    const rules = (style.stylers || []).map((styler) => {
-      return Object.entries(styler).map(([key, value]) => {
-        if (key === 'color' && typeof value === 'string') {
-          value = value.replace('#', '0x')
-        }
-        return `${key}:${value}`
-      }).join('|')
-    }).filter(Boolean).join('|')
-    return [feature, element, rules].filter(Boolean).join('|')
-  }).filter(Boolean)
+function toCssUnit(value: string | number): string {
+  return typeof value === 'number' ? `${value}px` : value
 }
 
-const placeholder = computed(() => {
-  let center = options.value.center
-  if (center && typeof center === 'object') {
-    center = `${center.lat},${center.lng}`
-  }
-  // @ts-expect-error lazy type
-  const placeholderOptions: PlaceholderOptions = defu(props.placeholderOptions, {
-    // only map option values
-    zoom: options.value.zoom,
-    center,
-  }, {
-    size: `${props.width}x${props.height}`,
-    // Only include API key if not using proxy (proxy injects it server-side)
-    key: proxyConfig?.enabled ? undefined : apiKey,
-    scale: 2, // we assume a high DPI to avoid hydration issues
-    style: props.mapOptions?.styles ? transformMapStyles(props.mapOptions.styles) : undefined,
-    map_id: currentMapId.value,
-  })
-
-  const baseUrl = proxyConfig?.enabled
-    ? '/_scripts/proxy/google-static-maps'
-    : 'https://maps.googleapis.com/maps/api/staticmap'
-
-  return withQuery(baseUrl, placeholderOptions as QueryObject)
-})
-
-const placeholderAttrs = computed(() => {
-  return defu(props.placeholderAttrs, {
-    src: placeholder.value,
-    alt: 'Google Maps Static Map',
-    loading: props.aboveTheFold ? 'eager' : 'lazy',
-    style: {
-      cursor: 'pointer',
-      width: '100%',
-      objectFit: 'cover',
-      height: '100%',
-    },
-  } satisfies ImgHTMLAttributes)
-})
-
 const rootAttrs = computed(() => {
   return defu(props.rootAttrs, {
     'aria-busy': status.value === 'loading',
     'aria-label': status.value === 'awaitingLoad'
-      ? 'Google Maps Static Map'
+      ? 'Google Maps'
       : status.value === 'loading'
-        ? 'Google Maps Map Embed Loading'
-        : 'Google Maps Embed',
+        ? 'Google Maps Loading'
+        : 'Google Maps',
     'aria-live': 'polite',
     'role': 'application',
     'style': {
       cursor: 'pointer',
       position: 'relative',
       maxWidth: '100%',
-      width: `${props.width}px`,
-      height: `'auto'`,
-      aspectRatio: `${props.width}/${props.height}`,
+      width: toCssUnit(props.width),
+      height: toCssUnit(props.height),
     },
     ...(trigger instanceof Promise ? trigger.ssrAttrs || {} : {}),
   }) as HTMLAttributes
@@ -444,9 +351,7 @@ onBeforeUnmount(() => {
 <template>
   <div ref="rootEl" v-bind="rootAttrs">
     <div v-show="ready" ref="mapEl" :style="{ width: '100%', height: '100%', maxWidth: '100%' }" />
-    <slot v-if="!ready" :placeholder="placeholder" name="placeholder">
-      <img v-bind="placeholderAttrs">
-    </slot>
+    <slot v-if="!ready" name="placeholder" />
     <slot v-if="status !== 'awaitingLoad' && !ready" name="loading">
       <ScriptAriaLoadingIndicator />
     </slot>
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
new file mode 100644
index 00000000..559fb94d
--- /dev/null
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
@@ -0,0 +1,258 @@
+<script lang="ts">
+/// <reference types="google.maps" />
+import type { QueryObject } from 'ufo'
+import type { ImgHTMLAttributes, ReservedProps } from 'vue'
+import { scriptRuntimeConfig } from '#nuxt-scripts/utils'
+import { defu } from 'defu'
+import { useHead, useRuntimeConfig } from 'nuxt/app'
+import { withQuery } from 'ufo'
+import { computed, onMounted, ref } from 'vue'
+</script>
+
+<script lang="ts" setup>
+export type StaticMapFormat = 'png' | 'jpg' | 'gif' | 'png8' | 'png32' | 'jpg-baseline'
+export type StaticMapType = 'roadmap' | 'satellite' | 'terrain' | 'hybrid'
+
+const props = withDefaults(defineProps<{
+  /**
+   * The center of the map. Accepts a "lat,lng" string or a LatLngLiteral object.
+   */
+  center?: string | { lat: number, lng: number }
+  /**
+   * Zoom level (0-21).
+   */
+  zoom?: number
+  /**
+   * Explicit pixel size for the Static Maps API request, e.g. "640x400".
+   * When omitted, the component measures its rendered dimensions on mount and uses those.
+   * Falls back to "640x400" during SSR or when dimensions can't be measured.
+   */
+  size?: `${number}x${number}`
+  /**
+   * Device pixel ratio for the static map image (1, 2, or 4).
+   */
+  scale?: 1 | 2 | 4
+  /**
+   * Image format.
+   */
+  format?: StaticMapFormat
+  /**
+   * Map type.
+   */
+  maptype?: StaticMapType
+  /**
+   * Cloud-based map styling ID.
+   */
+  mapId?: string
+  /**
+   * Map markers. Supports multiple markers via string array.
+   * @see https://developers.google.com/maps/documentation/maps-static/start#Markers
+   */
+  markers?: string | string[]
+  /**
+   * Polyline paths. Supports multiple paths via string array.
+   * @see https://developers.google.com/maps/documentation/maps-static/start#Paths
+   */
+  path?: string | string[]
+  /**
+   * Locations that should be visible on the map.
+   */
+  visible?: string | string[]
+  /**
+   * Map styling. Accepts raw Static Maps API style strings or Google Maps JS API MapTypeStyle objects.
+   */
+  style?: string | string[] | google.maps.MapTypeStyle[]
+  /**
+   * Language code for map labels.
+   */
+  language?: string
+  /**
+   * Region bias.
+   */
+  region?: string
+  /**
+   * Digital signature for requests without an API key.
+   */
+  signature?: string
+  /**
+   * API key override. When the proxy is enabled, this is ignored and the server-side key is used instead.
+   */
+  apiKey?: string
+  /**
+   * CSS width for the container element.
+   */
+  width?: number | string
+  /**
+   * CSS height for the container element.
+   */
+  height?: number | string
+  /**
+   * Image loading strategy.
+   */
+  loading?: 'eager' | 'lazy'
+  /**
+   * Object-fit for the image within its container.
+   */
+  objectFit?: 'cover' | 'contain' | 'fill' | 'none' | 'scale-down'
+  /**
+   * Additional attributes for the `<img>` element.
+   */
+  imgAttrs?: ImgHTMLAttributes & ReservedProps & Record<string, unknown>
+}>(), {
+  zoom: 15,
+  scale: 2,
+  loading: 'lazy',
+  objectFit: 'cover',
+  width: 640,
+  height: 400,
+})
+
+const apiKey = props.apiKey || scriptRuntimeConfig('googleMaps')?.apiKey
+const runtimeConfig = useRuntimeConfig()
+const proxyConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
+
+if (import.meta.dev) {
+  if (!apiKey && !proxyConfig?.enabled)
+    console.warn('[nuxt-scripts] ScriptGoogleMapsStaticMap requires a Google Maps API key with Static Maps API access. Set NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY in your .env, or enable the proxy via `scripts.registry.googleMaps`.')
+}
+
+const rootEl = ref<HTMLElement>()
+const measuredSize = ref<string>()
+
+onMounted(() => {
+  if (props.size || !rootEl.value)
+    return
+  const { offsetWidth, offsetHeight } = rootEl.value
+  if (offsetWidth > 0 && offsetHeight > 0) {
+    measuredSize.value = `${offsetWidth}x${offsetHeight}`
+  }
+})
+
+function toCssUnit(value: string | number): string {
+  return typeof value === 'number' ? `${value}px` : value
+}
+
+function isPixelValue(value: string | number): boolean {
+  if (typeof value === 'number')
+    return true
+  return /^\d+(px)?$/i.test(value)
+}
+
+function transformMapStyles(styles: google.maps.MapTypeStyle[]): string[] {
+  return styles.map((s) => {
+    const feature = s.featureType ? `feature:${s.featureType}` : ''
+    const element = s.elementType ? `element:${s.elementType}` : ''
+    const rules = (s.stylers || []).map((styler) => {
+      return Object.entries(styler).map(([key, value]) => {
+        if (key === 'color' && typeof value === 'string')
+          value = value.replace('#', '0x')
+        return `${key}:${value}`
+      }).join('|')
+    }).filter(Boolean).join('|')
+    return [feature, element, rules].filter(Boolean).join('|')
+  }).filter(Boolean)
+}
+
+function resolveStyle(style: string | string[] | google.maps.MapTypeStyle[] | undefined): string | string[] | undefined {
+  if (!style)
+    return undefined
+  if (typeof style === 'string')
+    return style
+  if (Array.isArray(style) && style.length > 0 && typeof style[0] === 'string')
+    return style as string[]
+  return transformMapStyles(style as google.maps.MapTypeStyle[])
+}
+
+function resolveCenter(center: string | { lat: number, lng: number } | undefined): string | undefined {
+  if (!center)
+    return undefined
+  if (typeof center === 'string')
+    return center
+  return `${center.lat},${center.lng}`
+}
+
+const resolvedSize = computed(() => {
+  if (props.size)
+    return props.size
+  if (measuredSize.value)
+    return measuredSize.value
+  // SSR fallback: derive from width/height if both are pixel values
+  if (isPixelValue(props.width) && isPixelValue(props.height))
+    return `${Number.parseInt(String(props.width))}x${Number.parseInt(String(props.height))}`
+  return '640x400'
+})
+
+const src = computed(() => {
+  const query: Record<string, any> = {
+    center: resolveCenter(props.center),
+    zoom: props.zoom,
+    size: resolvedSize.value,
+    scale: props.scale,
+    format: props.format,
+    maptype: props.maptype,
+    map_id: props.mapId,
+    markers: props.markers,
+    path: props.path,
+    visible: props.visible,
+    style: resolveStyle(props.style),
+    language: props.language,
+    region: props.region,
+    signature: props.signature,
+    key: proxyConfig?.enabled ? undefined : apiKey,
+  }
+
+  // Remove undefined values
+  for (const key of Object.keys(query)) {
+    if (query[key] === undefined)
+      delete query[key]
+  }
+
+  const baseUrl = proxyConfig?.enabled
+    ? '/_scripts/proxy/google-static-maps'
+    : 'https://maps.googleapis.com/maps/api/staticmap'
+
+  return withQuery(baseUrl, query as QueryObject)
+})
+
+const imgAttributes = computed(() => {
+  return defu(props.imgAttrs, {
+    src: src.value,
+    alt: 'Google Maps',
+    loading: props.loading,
+    style: {
+      width: '100%',
+      height: '100%',
+      objectFit: props.objectFit,
+      display: 'block',
+    },
+  } satisfies ImgHTMLAttributes)
+})
+
+const rootStyle = computed(() => ({
+  width: toCssUnit(props.width),
+  height: toCssUnit(props.height),
+  maxWidth: '100%',
+  overflow: 'hidden',
+}))
+
+if (import.meta.server) {
+  useHead({
+    link: [
+      {
+        rel: props.loading === 'eager' ? 'preconnect' : 'dns-prefetch',
+        href: proxyConfig?.enabled ? undefined : 'https://maps.googleapis.com',
+      },
+    ].filter(l => l.href),
+  })
+}
+
+defineExpose({ src })
+</script>
+
+<template>
+  <div ref="rootEl" :style="rootStyle">
+    <slot :src="src">
+      <img v-bind="imgAttributes">
+    </slot>
+  </div>
+</template>
diff --git a/playground/pages/third-parties/google-maps/center.vue b/playground/pages/third-parties/google-maps/center.vue
index de95dc08..9ab6131b 100644
--- a/playground/pages/third-parties/google-maps/center.vue
+++ b/playground/pages/third-parties/google-maps/center.vue
@@ -24,7 +24,6 @@ function changeQuery() {
         :width="1200"
         :height="600"
         :map-options="mapOptions"
-        above-the-fold
         @ready="() => {}"
       />
     </div>
diff --git a/playground/pages/third-parties/google-maps/emit-test.vue b/playground/pages/third-parties/google-maps/emit-test.vue
index 927e7e35..973a5b91 100644
--- a/playground/pages/third-parties/google-maps/emit-test.vue
+++ b/playground/pages/third-parties/google-maps/emit-test.vue
@@ -62,7 +62,6 @@ const circleOptions = {
         api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
         :width="800"
         :height="500"
-        above-the-fold
         :zoom="12"
         :map-options="{
           center: { lat: -33.87, lng: 151.21 },
diff --git a/playground/pages/third-parties/google-maps/geojson-test.vue b/playground/pages/third-parties/google-maps/geojson-test.vue
index 68a70bd8..da73b8f1 100644
--- a/playground/pages/third-parties/google-maps/geojson-test.vue
+++ b/playground/pages/third-parties/google-maps/geojson-test.vue
@@ -95,7 +95,6 @@ const secondGeoJson = {
         api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
         :width="800"
         :height="450"
-        above-the-fold
         :zoom="13"
         :map-options="{ center: { lat: -33.875, lng: 151.22 } }"
       >
diff --git a/playground/pages/third-parties/google-maps/markers.vue b/playground/pages/third-parties/google-maps/markers.vue
index 701abcd9..fe20447c 100644
--- a/playground/pages/third-parties/google-maps/markers.vue
+++ b/playground/pages/third-parties/google-maps/markers.vue
@@ -32,7 +32,6 @@ function removeMarkers() {
         :width="1200"
         :height="600"
         :map-options="{ center }"
-        above-the-fold
       >
         <ScriptGoogleMapsMarker
           v-for="(marker, i) in markers"
diff --git a/playground/pages/third-parties/google-maps/null.vue b/playground/pages/third-parties/google-maps/null.vue
index ce40dd37..271fe06b 100644
--- a/playground/pages/third-parties/google-maps/null.vue
+++ b/playground/pages/third-parties/google-maps/null.vue
@@ -19,7 +19,6 @@ function changeQuery() {
         api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
         :width="1200"
         :height="600"
-        above-the-fold
         :center="center"
       />
     </div>
diff --git a/playground/pages/third-parties/google-maps/nuxt-scripts.vue b/playground/pages/third-parties/google-maps/nuxt-scripts.vue
index 3ec39857..ec85b3f9 100644
--- a/playground/pages/third-parties/google-maps/nuxt-scripts.vue
+++ b/playground/pages/third-parties/google-maps/nuxt-scripts.vue
@@ -22,8 +22,17 @@ function changeQuery() {
         :width="640"
         :height="500"
         :map-options="mapOptions"
-        above-the-fold
-      />
+      >
+        <template #placeholder>
+          <ScriptGoogleMapsStaticMap
+            :center="mapOptions.center"
+            :width="640"
+            :height="500"
+            loading="eager"
+            api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
+          />
+        </template>
+      </ScriptGoogleMaps>
     </div>
     <div class="button-container">
       <button
diff --git a/playground/pages/third-parties/google-maps/overlay-animated.vue b/playground/pages/third-parties/google-maps/overlay-animated.vue
index a8578a71..b9f1db21 100644
--- a/playground/pages/third-parties/google-maps/overlay-animated.vue
+++ b/playground/pages/third-parties/google-maps/overlay-animated.vue
@@ -36,7 +36,6 @@ function close(id: number) {
       :zoom="12"
       :width="800"
       :height="500"
-      above-the-fold
       :map-options="{ mapId: 'DEMO_MAP_ID' }"
     >
       <ScriptGoogleMapsMarker
diff --git a/playground/pages/third-parties/google-maps/overlay-popup.vue b/playground/pages/third-parties/google-maps/overlay-popup.vue
index 28ca8b59..95054854 100644
--- a/playground/pages/third-parties/google-maps/overlay-popup.vue
+++ b/playground/pages/third-parties/google-maps/overlay-popup.vue
@@ -23,7 +23,6 @@ const places = [
       :zoom="12"
       :width="800"
       :height="500"
-      above-the-fold
       :map-options="{ mapId: 'DEMO_MAP_ID' }"
     >
       <ScriptGoogleMapsMarker
diff --git a/playground/pages/third-parties/google-maps/query.vue b/playground/pages/third-parties/google-maps/query.vue
index b1334c5d..9a644870 100644
--- a/playground/pages/third-parties/google-maps/query.vue
+++ b/playground/pages/third-parties/google-maps/query.vue
@@ -21,7 +21,6 @@ function changeQuery() {
         :width="1200"
         :height="600"
         :center="center"
-        above-the-fold
       />
     </div>
     <div class="button-container">
diff --git a/playground/pages/third-parties/google-maps/sfcs.vue b/playground/pages/third-parties/google-maps/sfcs.vue
index ed4e565e..c3617dac 100644
--- a/playground/pages/third-parties/google-maps/sfcs.vue
+++ b/playground/pages/third-parties/google-maps/sfcs.vue
@@ -92,7 +92,6 @@ whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
       api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
       :width="1280"
       :height="720"
-      above-the-fold
       :zoom="zoom"
       :map-options="{
         center: { lat: -34.397, lng: 150.644 },
diff --git a/playground/pages/third-parties/google-maps/styled.vue b/playground/pages/third-parties/google-maps/styled.vue
index 0e6c33d5..0c562215 100644
--- a/playground/pages/third-parties/google-maps/styled.vue
+++ b/playground/pages/third-parties/google-maps/styled.vue
@@ -12,7 +12,6 @@ const mapOptions = {
         api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
         :width="1200"
         :height="600"
-        above-the-fold
         :map-options="mapOptions"
       />
     </div>

From 335a9535cb65be8c0db8af9ff2422edfef0dd9c6 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 26 Mar 2026 15:04:55 +1100
Subject: [PATCH 2/4] fix: move regex to module scope for lint compliance

---
 .../components/GoogleMaps/ScriptGoogleMapsStaticMap.vue       | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
index 559fb94d..e647f3bd 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
@@ -132,10 +132,12 @@ function toCssUnit(value: string | number): string {
   return typeof value === 'number' ? `${value}px` : value
 }
 
+const PIXEL_VALUE_RE = /^\d+(?:px)?$/i
+
 function isPixelValue(value: string | number): boolean {
   if (typeof value === 'number')
     return true
-  return /^\d+(px)?$/i.test(value)
+  return PIXEL_VALUE_RE.test(value)
 }
 
 function transformMapStyles(styles: google.maps.MapTypeStyle[]): string[] {

From f64da30ad9c5a3cf461e7faa6f2df1fd641fa434 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 26 Mar 2026 16:25:23 +1100
Subject: [PATCH 3/4] fix: address CodeRabbit review + add docs for
 ScriptGoogleMapsStaticMap

- Restrict scale prop to 1 | 2 (matches Static Maps API)
- Explicit apiKey prop now takes priority over proxy
- Clamp auto-measured sizes to 640x640 API limit
- Remove hardcoded API key from playground
- Add ScriptGoogleMapsStaticMap API doc page
- Update ScriptGoogleMaps docs for new placeholder pattern
- Add Google Maps breaking changes to v0-to-v1 migration guide
---
 .../docs/4.migration-guide/1.v0-to-v1.md      | 36 +++++++
 .../google-maps/2.api/1.script-google-maps.md | 16 +--
 .../google-maps/2.api/1b.static-map.md        | 99 +++++++++++++++++++
 .../GoogleMaps/ScriptGoogleMapsStaticMap.vue  | 25 +++--
 .../google-maps/nuxt-scripts.vue              |  2 -
 5 files changed, 160 insertions(+), 18 deletions(-)
 create mode 100644 docs/content/scripts/google-maps/2.api/1b.static-map.md

diff --git a/docs/content/docs/4.migration-guide/1.v0-to-v1.md b/docs/content/docs/4.migration-guide/1.v0-to-v1.md
index 2c264404..6e2389c5 100644
--- a/docs/content/docs/4.migration-guide/1.v0-to-v1.md
+++ b/docs/content/docs/4.migration-guide/1.v0-to-v1.md
@@ -301,6 +301,42 @@ Default `object-fit` changed from `contain` to `cover`:
 
 Player instances are now properly isolated. Remove any workarounds for multiple players.
 
+### Google Maps Static Placeholder ([#673](https://github.com/nuxt/scripts/pull/673))
+
+The built-in static map placeholder was extracted into a standalone [`<ScriptGoogleMapsStaticMap>`{lang="html"}](/scripts/google-maps/api/static-map) component. The following props were removed from `<ScriptGoogleMaps>`{lang="html"}:
+
+- `placeholderOptions`
+- `placeholderAttrs`
+- `aboveTheFold`
+
+The `#placeholder` slot no longer passes a `placeholder` URL string. It is now empty by default.
+
+```diff
+<!-- Before -->
+<ScriptGoogleMaps
+  :center="center"
+  :zoom="7"
+  above-the-fold
+  :placeholder-options="{ maptype: 'satellite' }"
+  :placeholder-attrs="{ class: 'rounded' }"
+/>
+
+<!-- After -->
++<ScriptGoogleMaps :center="center" :zoom="7">
++  <template #placeholder>
++    <ScriptGoogleMapsStaticMap
++      :center="center"
++      :zoom="7"
++      loading="eager"
++      maptype="satellite"
++      :img-attrs="{ class: 'rounded' }"
++    />
++  </template>
++</ScriptGoogleMaps>
+```
+
+The new component can also be used standalone for store locators, contact pages, and directions previews without loading the interactive Maps API.
+
 ### Google Tag Manager
 
 #### onBeforeGtmStart Callback
diff --git a/docs/content/scripts/google-maps/2.api/1.script-google-maps.md b/docs/content/scripts/google-maps/2.api/1.script-google-maps.md
index 12922ad9..425a400d 100644
--- a/docs/content/scripts/google-maps/2.api/1.script-google-maps.md
+++ b/docs/content/scripts/google-maps/2.api/1.script-google-maps.md
@@ -9,7 +9,7 @@ The [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps){lang="html"} compo
 
 It's optimized for performance by using the [Element Event Triggers](/docs/guides/script-triggers#element-event-triggers), only loading the Google Maps when specific elements events happen.
 
-Before Google Maps loads, it shows a placeholder using [Maps Static API](https://developers.google.com/maps/documentation/maps-static).
+The `#placeholder` slot is empty by default. Use [`<ScriptGoogleMapsStaticMap>`{lang="html"}](/scripts/google-maps/api/static-map) inside it to show a static map image while the interactive map loads.
 
 By default, it will load on the `mouseenter`, `mouseover`, and `mousedown` events.
 
@@ -124,15 +124,17 @@ override this component. Make sure you provide a loading indicator.
 
 **placeholder**
 
-This slot displays a placeholder image before Google Maps loads. By default, this will show the Google Maps Static API image for the map.
-
-Provide custom `#placeholder` content without rendering the provided `placeholder` URL to skip the Static Maps API request and avoid those charges.
+The placeholder slot is empty by default. Use [`<ScriptGoogleMapsStaticMap>`{lang="html"}](/scripts/google-maps/api/static-map) to show a static map preview while the interactive map loads.
 
 ```vue
 <template>
-  <ScriptGoogleMaps>
-    <template #placeholder="{ placeholder }">
-      <img :src="placeholder">
+  <ScriptGoogleMaps :center="center" :zoom="7">
+    <template #placeholder>
+      <ScriptGoogleMapsStaticMap
+        :center="center"
+        :zoom="7"
+        loading="eager"
+      />
     </template>
   </ScriptGoogleMaps>
 </template>
diff --git a/docs/content/scripts/google-maps/2.api/1b.static-map.md b/docs/content/scripts/google-maps/2.api/1b.static-map.md
new file mode 100644
index 00000000..3473c259
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/1b.static-map.md
@@ -0,0 +1,99 @@
+---
+title: <ScriptGoogleMapsStaticMap>
+---
+
+Renders a [Google Maps Static API](https://developers.google.com/maps/documentation/maps-static) image. Use standalone for static map previews, or drop into the `#placeholder` slot of [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) for a loading placeholder.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsStaticMap"}
+::
+
+## Usage
+
+### Standalone
+
+Display a static map without loading the interactive Google Maps JavaScript API.
+
+```vue
+<template>
+  <ScriptGoogleMapsStaticMap
+    center="51.95,19.13"
+    :zoom="7"
+    width="100%"
+    height="300"
+  />
+</template>
+```
+
+### As Placeholder
+
+Use inside [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) to show a static map while the interactive map loads.
+
+```vue
+<template>
+  <ScriptGoogleMaps :center="center" :zoom="7">
+    <template #placeholder>
+      <ScriptGoogleMapsStaticMap
+        :center="center"
+        :zoom="7"
+        loading="eager"
+        maptype="satellite"
+      />
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `center` | `string \| { lat: number, lng: number }` | — | Map center as `"lat,lng"` string or `LatLngLiteral`. |
+| `zoom` | `number` | `15` | Zoom level (0–21). |
+| `size` | `` `${number}x${number}` `` | auto | Explicit pixel size for the API request. When omitted, measures the rendered container on mount. Falls back to `640x400` during SSR. |
+| `scale` | `1 \| 2` | `2` | Device pixel ratio. |
+| `format` | `StaticMapFormat` | — | Image format: `png`, `jpg`, `gif`, `png8`, `png32`, `jpg-baseline`. |
+| `maptype` | `StaticMapType` | — | Map type: `roadmap`, `satellite`, `terrain`, `hybrid`. |
+| `mapId` | `string` | — | Cloud-based map styling ID. |
+| `markers` | `string \| string[]` | — | [Marker descriptors](https://developers.google.com/maps/documentation/maps-static/start#Markers). |
+| `path` | `string \| string[]` | — | [Polyline path descriptors](https://developers.google.com/maps/documentation/maps-static/start#Paths). |
+| `visible` | `string \| string[]` | — | Locations that should be visible on the map. |
+| `style` | `string \| string[] \| MapTypeStyle[]` | — | Map styling. Accepts raw Static Maps API style strings or Google Maps JS API `MapTypeStyle[]` objects. |
+| `language` | `string` | — | Language code for map labels. |
+| `region` | `string` | — | Region bias. |
+| `signature` | `string` | — | Digital signature for keyless requests. |
+| `apiKey` | `string` | — | API key override. When the proxy is enabled and no explicit key is passed, the server-side key is used instead. |
+| `width` | `number \| string` | `640` | CSS width for the container. |
+| `height` | `number \| string` | `400` | CSS height for the container. |
+| `loading` | `'eager' \| 'lazy'` | `'lazy'` | Image loading strategy. |
+| `objectFit` | `string` | `'cover'` | Object-fit for the `<img>`{lang="html"} within its container. |
+| `imgAttrs` | `ImgHTMLAttributes` | — | Additional attributes for the `<img>`{lang="html"} element. |
+
+## Size Handling
+
+When `size` is not provided, the component:
+
+1. **Client-side**: Measures the container's pixel dimensions on mount and clamps to the [Static Maps API limit](https://developers.google.com/maps/documentation/maps-static/start) of 640x640 (preserving aspect ratio).
+2. **SSR**: Derives from `width`/`height` props if both are pixel values.
+3. **Fallback**: Uses `640x400`.
+
+Set `size` explicitly to bypass auto-measurement.
+
+## Proxy Support
+
+When `googleMaps` is configured in `scripts.registry`, a server-side proxy is automatically enabled. The component routes requests through the proxy unless an explicit `apiKey` prop is provided.
+
+## Slots
+
+**default**
+
+Override the `<img>`{lang="html"} element with a custom template. Receives `{ src }` with the computed Static Maps URL.
+
+```vue
+<template>
+  <ScriptGoogleMapsStaticMap center="51.95,19.13" :zoom="7">
+    <template #default="{ src }">
+      <img :src="src" alt="Custom static map" class="rounded-lg shadow">
+    </template>
+  </ScriptGoogleMapsStaticMap>
+</template>
+```
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
index e647f3bd..ca9caf33 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsStaticMap.vue
@@ -29,9 +29,9 @@ const props = withDefaults(defineProps<{
    */
   size?: `${number}x${number}`
   /**
-   * Device pixel ratio for the static map image (1, 2, or 4).
+   * Device pixel ratio for the static map image (1 or 2).
    */
-  scale?: 1 | 2 | 4
+  scale?: 1 | 2
   /**
    * Image format.
    */
@@ -107,24 +107,31 @@ const props = withDefaults(defineProps<{
   height: 400,
 })
 
-const apiKey = props.apiKey || scriptRuntimeConfig('googleMaps')?.apiKey
 const runtimeConfig = useRuntimeConfig()
 const proxyConfig = (runtimeConfig.public['nuxt-scripts'] as any)?.googleStaticMapsProxy
+const apiKey = props.apiKey || scriptRuntimeConfig('googleMaps')?.apiKey
+// Only use the proxy when no explicit API key is provided and the proxy is enabled
+const useProxy = !props.apiKey && proxyConfig?.enabled
 
 if (import.meta.dev) {
-  if (!apiKey && !proxyConfig?.enabled)
+  if (!apiKey && !useProxy)
     console.warn('[nuxt-scripts] ScriptGoogleMapsStaticMap requires a Google Maps API key with Static Maps API access. Set NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY in your .env, or enable the proxy via `scripts.registry.googleMaps`.')
 }
 
 const rootEl = ref<HTMLElement>()
 const measuredSize = ref<string>()
 
+function clampStaticMapSize(width: number, height: number, max = 640): `${number}x${number}` {
+  const ratio = Math.min(1, max / Math.max(width, height))
+  return `${Math.max(1, Math.floor(width * ratio))}x${Math.max(1, Math.floor(height * ratio))}` as `${number}x${number}`
+}
+
 onMounted(() => {
   if (props.size || !rootEl.value)
     return
   const { offsetWidth, offsetHeight } = rootEl.value
   if (offsetWidth > 0 && offsetHeight > 0) {
-    measuredSize.value = `${offsetWidth}x${offsetHeight}`
+    measuredSize.value = clampStaticMapSize(offsetWidth, offsetHeight)
   }
 })
 
@@ -180,7 +187,7 @@ const resolvedSize = computed(() => {
     return measuredSize.value
   // SSR fallback: derive from width/height if both are pixel values
   if (isPixelValue(props.width) && isPixelValue(props.height))
-    return `${Number.parseInt(String(props.width))}x${Number.parseInt(String(props.height))}`
+    return clampStaticMapSize(Number.parseInt(String(props.width)), Number.parseInt(String(props.height)))
   return '640x400'
 })
 
@@ -200,7 +207,7 @@ const src = computed(() => {
     language: props.language,
     region: props.region,
     signature: props.signature,
-    key: proxyConfig?.enabled ? undefined : apiKey,
+    key: useProxy ? undefined : apiKey,
   }
 
   // Remove undefined values
@@ -209,7 +216,7 @@ const src = computed(() => {
       delete query[key]
   }
 
-  const baseUrl = proxyConfig?.enabled
+  const baseUrl = useProxy
     ? '/_scripts/proxy/google-static-maps'
     : 'https://maps.googleapis.com/maps/api/staticmap'
 
@@ -242,7 +249,7 @@ if (import.meta.server) {
     link: [
       {
         rel: props.loading === 'eager' ? 'preconnect' : 'dns-prefetch',
-        href: proxyConfig?.enabled ? undefined : 'https://maps.googleapis.com',
+        href: useProxy ? undefined : 'https://maps.googleapis.com',
       },
     ].filter(l => l.href),
   })
diff --git a/playground/pages/third-parties/google-maps/nuxt-scripts.vue b/playground/pages/third-parties/google-maps/nuxt-scripts.vue
index ec85b3f9..1ebd7436 100644
--- a/playground/pages/third-parties/google-maps/nuxt-scripts.vue
+++ b/playground/pages/third-parties/google-maps/nuxt-scripts.vue
@@ -18,7 +18,6 @@ function changeQuery() {
     <div>
       <ScriptGoogleMaps
         ref="googleMapsRef"
-        api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
         :width="640"
         :height="500"
         :map-options="mapOptions"
@@ -29,7 +28,6 @@ function changeQuery() {
             :width="640"
             :height="500"
             loading="eager"
-            api-key="AIzaSyAOEIQ_xOdLx2dNwnFMzyJoswwvPCTcGzU"
           />
         </template>
       </ScriptGoogleMaps>

From 3ad32358f6a8ad3576d3a15b99b4cf12078f1c01 Mon Sep 17 00:00:00 2001
From: Harlan Wilton <harlan@harlanzw.com>
Date: Thu, 26 Mar 2026 16:46:43 +1100
Subject: [PATCH 4/4] fix: resolve doc linting issues (em-dashes, passive
 voice)

---
 .../docs/4.migration-guide/1.v0-to-v1.md      |  4 +--
 .../google-maps/2.api/1b.static-map.md        | 30 +++++++++----------
 2 files changed, 17 insertions(+), 17 deletions(-)

diff --git a/docs/content/docs/4.migration-guide/1.v0-to-v1.md b/docs/content/docs/4.migration-guide/1.v0-to-v1.md
index 6e2389c5..7fe33de0 100644
--- a/docs/content/docs/4.migration-guide/1.v0-to-v1.md
+++ b/docs/content/docs/4.migration-guide/1.v0-to-v1.md
@@ -303,7 +303,7 @@ Player instances are now properly isolated. Remove any workarounds for multiple
 
 ### Google Maps Static Placeholder ([#673](https://github.com/nuxt/scripts/pull/673))
 
-The built-in static map placeholder was extracted into a standalone [`<ScriptGoogleMapsStaticMap>`{lang="html"}](/scripts/google-maps/api/static-map) component. The following props were removed from `<ScriptGoogleMaps>`{lang="html"}:
+v1 extracts the built-in static map placeholder into a standalone [`<ScriptGoogleMapsStaticMap>`{lang="html"}](/scripts/google-maps/api/static-map) component. This removes the following props from `<ScriptGoogleMaps>`{lang="html"}:
 
 - `placeholderOptions`
 - `placeholderAttrs`
@@ -335,7 +335,7 @@ The `#placeholder` slot no longer passes a `placeholder` URL string. It is now e
 +</ScriptGoogleMaps>
 ```
 
-The new component can also be used standalone for store locators, contact pages, and directions previews without loading the interactive Maps API.
+Use the new component standalone for store locators, contact pages, and directions previews without loading the interactive Maps API.
 
 ### Google Tag Manager
 
diff --git a/docs/content/scripts/google-maps/2.api/1b.static-map.md b/docs/content/scripts/google-maps/2.api/1b.static-map.md
index 3473c259..9f84a93d 100644
--- a/docs/content/scripts/google-maps/2.api/1b.static-map.md
+++ b/docs/content/scripts/google-maps/2.api/1b.static-map.md
@@ -47,26 +47,26 @@ Use inside [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-g
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `center` | `string \| { lat: number, lng: number }` | — | Map center as `"lat,lng"` string or `LatLngLiteral`. |
-| `zoom` | `number` | `15` | Zoom level (0–21). |
+| `center` | `string \| { lat: number, lng: number }` | | Map center as `"lat,lng"` string or `LatLngLiteral`. |
+| `zoom` | `number` | `15` | Zoom level (0 to 21). |
 | `size` | `` `${number}x${number}` `` | auto | Explicit pixel size for the API request. When omitted, measures the rendered container on mount. Falls back to `640x400` during SSR. |
 | `scale` | `1 \| 2` | `2` | Device pixel ratio. |
-| `format` | `StaticMapFormat` | — | Image format: `png`, `jpg`, `gif`, `png8`, `png32`, `jpg-baseline`. |
-| `maptype` | `StaticMapType` | — | Map type: `roadmap`, `satellite`, `terrain`, `hybrid`. |
-| `mapId` | `string` | — | Cloud-based map styling ID. |
-| `markers` | `string \| string[]` | — | [Marker descriptors](https://developers.google.com/maps/documentation/maps-static/start#Markers). |
-| `path` | `string \| string[]` | — | [Polyline path descriptors](https://developers.google.com/maps/documentation/maps-static/start#Paths). |
-| `visible` | `string \| string[]` | — | Locations that should be visible on the map. |
-| `style` | `string \| string[] \| MapTypeStyle[]` | — | Map styling. Accepts raw Static Maps API style strings or Google Maps JS API `MapTypeStyle[]` objects. |
-| `language` | `string` | — | Language code for map labels. |
-| `region` | `string` | — | Region bias. |
-| `signature` | `string` | — | Digital signature for keyless requests. |
-| `apiKey` | `string` | — | API key override. When the proxy is enabled and no explicit key is passed, the server-side key is used instead. |
+| `format` | `StaticMapFormat` | | Image format: `png`, `jpg`, `gif`, `png8`, `png32`, `jpg-baseline`. |
+| `maptype` | `StaticMapType` | | Map type: `roadmap`, `satellite`, `terrain`, `hybrid`. |
+| `mapId` | `string` | | Cloud-based map styling ID. |
+| `markers` | `string \| string[]` | | [Marker descriptors](https://developers.google.com/maps/documentation/maps-static/start#Markers). |
+| `path` | `string \| string[]` | | [Polyline path descriptors](https://developers.google.com/maps/documentation/maps-static/start#Paths). |
+| `visible` | `string \| string[]` | | Locations that should be visible on the map. |
+| `style` | `string \| string[] \| MapTypeStyle[]` | | Map styling. Accepts raw Static Maps API style strings or Google Maps JS API `MapTypeStyle[]` objects. |
+| `language` | `string` | | Language code for map labels. |
+| `region` | `string` | | Region bias. |
+| `signature` | `string` | | Digital signature for keyless requests. |
+| `apiKey` | `string` | | API key override. Takes priority over the proxy; the component falls back to the server-side key when omitted. |
 | `width` | `number \| string` | `640` | CSS width for the container. |
 | `height` | `number \| string` | `400` | CSS height for the container. |
 | `loading` | `'eager' \| 'lazy'` | `'lazy'` | Image loading strategy. |
 | `objectFit` | `string` | `'cover'` | Object-fit for the `<img>`{lang="html"} within its container. |
-| `imgAttrs` | `ImgHTMLAttributes` | — | Additional attributes for the `<img>`{lang="html"} element. |
+| `imgAttrs` | `ImgHTMLAttributes` | | Additional attributes for the `<img>`{lang="html"} element. |
 
 ## Size Handling
 
@@ -80,7 +80,7 @@ Set `size` explicitly to bypass auto-measurement.
 
 ## Proxy Support
 
-When `googleMaps` is configured in `scripts.registry`, a server-side proxy is automatically enabled. The component routes requests through the proxy unless an explicit `apiKey` prop is provided.
+Configuring `googleMaps` in `scripts.registry` enables a server-side proxy automatically. The component routes requests through the proxy unless you provide an explicit `apiKey` prop.
 
 ## Slots