diff --git a/docs/content/scripts/google-maps/.navigation.yml b/docs/content/scripts/google-maps/.navigation.yml
new file mode 100644
index 00000000..b7dd8d23
--- /dev/null
+++ b/docs/content/scripts/google-maps/.navigation.yml
@@ -0,0 +1 @@
+title: Google Maps
diff --git a/docs/content/scripts/google-maps/1.guides/.navigation.yml b/docs/content/scripts/google-maps/1.guides/.navigation.yml
new file mode 100644
index 00000000..f1ad8d56
--- /dev/null
+++ b/docs/content/scripts/google-maps/1.guides/.navigation.yml
@@ -0,0 +1,2 @@
+title: Guides
+icon: i-ph-book-duotone
diff --git a/docs/content/scripts/google-maps/1.guides/1.performance.md b/docs/content/scripts/google-maps/1.guides/1.performance.md
new file mode 100644
index 00000000..36cf9581
--- /dev/null
+++ b/docs/content/scripts/google-maps/1.guides/1.performance.md
@@ -0,0 +1,127 @@
+---
+title: Performance
+---
+
+`ScriptGoogleMaps` is optimized by default: the JavaScript API only loads when the user interacts with the map. Before that, a lightweight static image placeholder is shown.
+
+## Loading Strategies
+
+### Default: Lazy (Recommended)
+
+By default, the map loads on `mouseenter`, `mouseover`, or `mousedown`. Most page visitors never interact with the map, so you avoid the Maps JavaScript API charge for those sessions.
+
+```vue
+<template>
+  <!-- Loads JS API on first hover/click -->
+  <ScriptGoogleMaps
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+### Immediate Loading
+
+Forces the JavaScript API to load with the page. Use this only when the map is the primary content and you need it interactive from the start.
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    trigger="immediate"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+::callout{color="amber"}
+Immediate loading charges the Maps JavaScript API ($7/1000) on every page view. Only use this when the map is essential to the page experience.
+::
+
+### Custom Triggers
+
+You can control exactly when the map loads using any [Element Event Trigger](/docs/guides/script-triggers#element-event-triggers).
+
+```vue
+<template>
+  <!-- Only load on explicit click -->
+  <ScriptGoogleMaps trigger="mousedown" />
+
+  <!-- Load when element enters viewport -->
+  <ScriptGoogleMaps trigger="visible" />
+</template>
+```
+
+## Placeholder Optimization
+
+### Above the Fold
+
+When the map is visible without scrolling, mark it for priority loading. This sets the placeholder image to `loading="eager"` and adds a `preconnect` hint.
+
+```vue
+<template>
+  <ScriptGoogleMaps above-the-fold />
+</template>
+```
+
+### Custom Placeholder
+
+Replace the default Google Static Maps image with your own custom image to avoid Static Maps API charges. Useful when you have a screenshot or illustration of the map area.
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #placeholder>
+      <img src="/map-preview.webp" alt="Map of Sydney" style="width: 100%; height: 100%; object-fit: cover;">
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+You can also access the generated static map URL if you want to use it with custom styling. Note that rendering the `placeholder` URL still makes a Static Maps API request and incurs charges:
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #placeholder="{ placeholder }">
+      <img :src="placeholder" alt="Map" style="filter: grayscale(1);">
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+### Loading State
+
+Show a custom indicator while the JavaScript API loads:
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #loading>
+      <div style="display: flex; align-items: center; justify-content: center; height: 100%;">
+        Loading map...
+      </div>
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+## Marker Performance
+
+When rendering many markers, use `ScriptGoogleMapsMarkerClusterer` to group nearby markers. This significantly reduces DOM elements and improves pan/zoom performance.
+
+```vue
+<template>
+  <ScriptGoogleMaps :center="center" :zoom="10">
+    <ScriptGoogleMapsMarkerClusterer>
+      <ScriptGoogleMapsAdvancedMarkerElement
+        v-for="place in places"
+        :key="place.id"
+        :position="place.position"
+      />
+    </ScriptGoogleMapsMarkerClusterer>
+  </ScriptGoogleMaps>
+</template>
+```
+
+See [Billing & Permissions](/scripts/google-maps/guides/billing) for a full cost breakdown and optimization strategies.
diff --git a/docs/content/scripts/google-maps/1.guides/2.programmatic-api.md b/docs/content/scripts/google-maps/1.guides/2.programmatic-api.md
new file mode 100644
index 00000000..5eea73eb
--- /dev/null
+++ b/docs/content/scripts/google-maps/1.guides/2.programmatic-api.md
@@ -0,0 +1,130 @@
+---
+title: Programmatic API
+---
+
+The `ScriptGoogleMaps` component exposes its internal APIs via template ref, giving you full control beyond what the declarative SFC components provide.
+
+## Accessing the API
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+function onReady({ googleMaps, map, createAdvancedMapMarker, resolveQueryToLatLng, importLibrary }) {
+  // All APIs available here
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps ref="mapRef" @ready="onReady" />
+</template>
+```
+
+### Exposed Properties
+
+| Property | Type | Description |
+|---|---|---|
+| `googleMaps` | `Ref<typeof google.maps>`{lang="html"} | The Google Maps API namespace |
+| `map` | `ShallowRef<google.maps.Map>`{lang="html"} | The map instance |
+| `createAdvancedMapMarker` | `(options?) => Promise<AdvancedMarkerElement>`{lang="html"} | Create a marker programmatically |
+| `resolveQueryToLatLng` | `(query: string) => Promise<LatLng>`{lang="html"} | Geocode a location string |
+| `importLibrary` | `(key: string) => Promise<any>`{lang="html"} | Load an additional Google Maps library |
+
+## Creating Markers Programmatically
+
+For cases where declarative `v-for` markers aren't flexible enough (dynamic data, imperative creation logic), use `createAdvancedMapMarker`:
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+async function addMarkerAtCenter() {
+  const map = mapRef.value.map.value
+  const center = map.getCenter()
+  const marker = await mapRef.value.createAdvancedMapMarker({
+    position: { lat: center.lat(), lng: center.lng() },
+    title: 'New Marker',
+  })
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps ref="mapRef" :center="{ lat: -33.8688, lng: 151.2093 }" :zoom="12" />
+  <button @click="addMarkerAtCenter">
+    Add Marker at Center
+  </button>
+</template>
+```
+
+::callout
+For most use cases, prefer the declarative `ScriptGoogleMapsAdvancedMarkerElement` component with `v-for`. Use the programmatic API when you need fine-grained control over marker lifecycle or are integrating with external data sources.
+::
+
+## Geocoding Queries
+
+Convert location strings to coordinates using `resolveQueryToLatLng`. When you enable the registry proxy, this resolves server-side (cheaper, API key hidden). Otherwise it falls back to the client-side Places API.
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+async function goToLocation(query: string) {
+  const latLng = await mapRef.value.resolveQueryToLatLng(query)
+  mapRef.value.map.value.setCenter(latLng)
+  mapRef.value.map.value.setZoom(15)
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps ref="mapRef" :center="{ lat: 0, lng: 0 }" :zoom="2" />
+  <button @click="goToLocation('Eiffel Tower, Paris')">
+    Go to Paris
+  </button>
+</template>
+```
+
+## Importing Libraries
+
+Google Maps splits functionality into libraries that load on demand. Use `importLibrary` to access geometry, drawing, places, and visualization APIs:
+
+```vue
+<script setup lang="ts">
+const mapRef = ref()
+
+async function measureDistance(a: google.maps.LatLng, b: google.maps.LatLng) {
+  const geometry = await mapRef.value.importLibrary('geometry')
+  return geometry.spherical.computeDistanceBetween(a, b)
+}
+</script>
+```
+
+Available libraries: `marker`, `places`, `geometry`, `drawing`, `visualization`
+
+## Subscribing to Map Events
+
+Use the `@ready` event to access the map instance and subscribe to native Google Maps events:
+
+```vue
+<script setup lang="ts">
+function onReady({ map }) {
+  watch(map, (m) => {
+    if (!m)
+      return
+    m.addListener('zoom_changed', () => {
+      console.log('Zoom:', m.getZoom())
+    })
+    m.addListener('center_changed', () => {
+      console.log('Center:', m.getCenter()?.toJSON())
+    })
+    m.addListener('idle', () => {
+      // Map finished moving, good time to fetch data for visible bounds
+      const bounds = m.getBounds()
+    })
+  }, { immediate: true })
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps @ready="onReady" />
+</template>
+```
diff --git a/docs/content/scripts/google-maps/1.guides/3.map-styling.md b/docs/content/scripts/google-maps/1.guides/3.map-styling.md
new file mode 100644
index 00000000..9f205999
--- /dev/null
+++ b/docs/content/scripts/google-maps/1.guides/3.map-styling.md
@@ -0,0 +1,105 @@
+---
+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.
+
+## JSON Styles
+
+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.
+
+```vue
+<script setup lang="ts">
+const mapOptions = {
+  styles: [
+    { elementType: 'labels', stylers: [{ visibility: 'off' }, { color: '#f49f53' }] },
+    { featureType: 'landscape', stylers: [{ color: '#f9ddc5' }, { lightness: -7 }] },
+    { featureType: 'road', stylers: [{ color: '#813033' }, { lightness: 43 }] },
+    { featureType: 'water', stylers: [{ color: '#1994bf' }, { saturation: -69 }, { gamma: 0.99 }, { lightness: 43 }] },
+    { featureType: 'poi.park', stylers: [{ color: '#645c20' }, { lightness: 39 }] },
+  ],
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps :map-options="mapOptions" />
+</template>
+```
+
+## Cloud-Based Map IDs
+
+Google's [Map Styling](https://developers.google.com/maps/documentation/cloud-customization) lets you create and manage styles in the Google Cloud Console, then apply them with a map ID.
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :map-options="{ mapId: 'YOUR_MAP_ID' }"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+::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.
+::
+
+## Dark Mode / Color Mode
+
+Switch map styles automatically based on the user's color mode preference. Provide a `mapIds` object with light and dark map IDs:
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+This auto-detects `@nuxtjs/color-mode` if installed. You can also control it manually with the `colorMode` prop:
+
+```vue
+<script setup lang="ts">
+const isDark = ref(false)
+</script>
+
+<template>
+  <ScriptGoogleMaps
+    :map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
+    :color-mode="isDark ? 'dark' : 'light'"
+  />
+  <button @click="isDark = !isDark">
+    Toggle Dark Mode
+  </button>
+</template>
+```
+
+## Combining Styles with Markers
+
+Custom-styled maps pair well with custom marker content for a cohesive look:
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :map-options="{ mapId: 'DARK_THEME_ID' }"
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="13"
+  >
+    <ScriptGoogleMapsAdvancedMarkerElement
+      v-for="place in places"
+      :key="place.id"
+      :position="place.position"
+    >
+      <template #content>
+        <div style="background: rgba(255,255,255,0.9); padding: 4px 8px; border-radius: 4px; font-size: 12px;">
+          {{ place.label }}
+        </div>
+      </template>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/1.guides/4.billing.md b/docs/content/scripts/google-maps/1.guides/4.billing.md
new file mode 100644
index 00000000..8313ce19
--- /dev/null
+++ b/docs/content/scripts/google-maps/1.guides/4.billing.md
@@ -0,0 +1,66 @@
+---
+title: Billing & Permissions
+---
+
+## Required API Permissions
+
+Your Google Cloud project needs these APIs enabled:
+
+| API | Required? | When it's used |
+|---|---|---|
+| [Maps JavaScript API](https://developers.google.com/maps/documentation/javascript/cloud-setup) | Yes | Interactive map rendering |
+| [Static Maps API](https://developers.google.com/maps/documentation/maps-static/cloud-setup) | Recommended | Placeholder image before JS loads (unless you provide a `#placeholder` slot) |
+| [Geocoding API](https://developers.google.com/maps/documentation/geocoding/cloud-setup) | Optional | Server-side geocode proxy for query strings (e.g. `center="Brooklyn Bridge, NY"`) |
+| [Places API](https://developers.google.com/maps/documentation/places/web-service/cloud-setup) | Optional | Client-side fallback when geocode proxy is unavailable and using query strings |
+
+## Cost Breakdown
+
+Google Maps uses a pay-per-use model. Here's what each interaction costs:
+
+| Action | API Charged | Cost per 1,000 | When it happens |
+|---|---|---|---|
+| Page loads with map placeholder | Static Maps API | $2 | Every page view (unless `#placeholder` slot overrides) |
+| User interacts with map (hover/click) | Maps JavaScript API | $7 | Only when user triggers the map to load |
+| Location query resolved server-side | Geocoding API | $5 | Only when using string queries like `"Sydney, Australia"` |
+| Location query resolved client-side | Places API | $17 | Fallback when geocode proxy is not enabled |
+
+### How Nuxt Scripts Minimizes Costs
+
+Nuxt Scripts is designed to reduce Google Maps billing:
+
+**Lazy loading**: The JavaScript API ($7/1000) only loads when a user interacts with the map. If they never hover or click, you only pay for the static placeholder ($2/1000).
+
+**Geocode proxy**: When you enable `googleMaps: true` in the registry, the server resolves location queries via the Geocoding API ($5/1000) instead of the client-side Places API ($17/1000). That's a 70% cost reduction for query resolution.
+
+**Static maps proxy**: Placeholder images are routed through your server, which enables caching. Repeated visits to the same page serve cached images instead of hitting Google's API again.
+
+### Cost Optimization Tips
+
+1. **Use coordinates, not queries**: Pass `center` as `{ lat, lng }` instead of `"Sydney, Australia"` to avoid geocoding charges entirely.
+
+2. **Provide a `#placeholder` slot**: Replace the static map image with your own placeholder to eliminate Static Maps API charges.
+
+    ```vue
+    <ScriptGoogleMaps>
+      <template #placeholder>
+        <img src="/my-map-placeholder.webp" alt="Map">
+      </template>
+    </ScriptGoogleMaps>
+    ```
+
+3. **Use `trigger="immediate"`** only when needed: The default trigger (mouseover/mousedown) means most page views won't load the JS API. Setting `trigger="immediate"` charges $7/1000 on every page view.
+
+4. **Consider Iframe Embed for non-interactive maps**: If you don't need full interactivity, the [Google Maps Embed API](https://developers.google.com/maps/documentation/embed/get-started) is free and you can load it with `useScript()`{lang="ts"}.
+
+## Monthly Cost Estimates
+
+Assuming 100,000 page views per month:
+
+| Scenario | Monthly Cost |
+|---|---|
+| Static placeholder only (no interaction) | ~$200 |
+| 20% of visitors interact with map | ~$340 |
+| All visitors interact with map | ~$900 |
+| Custom `#placeholder` slot, 20% interact | ~$140 |
+
+These estimates assume you have Google's [$200/month free credit](https://mapsplatform.google.com/pricing/). Most small to mid-size sites fall within the free tier.
diff --git a/docs/content/scripts/google-maps/2.api/.navigation.yml b/docs/content/scripts/google-maps/2.api/.navigation.yml
new file mode 100644
index 00000000..e506a40e
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/.navigation.yml
@@ -0,0 +1,2 @@
+title: API
+icon: i-lucide-code
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
new file mode 100644
index 00000000..d54a93a7
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/1.script-google-maps.md
@@ -0,0 +1,130 @@
+---
+title: <ScriptGoogleMaps>
+---
+
+The [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps){lang="html"} component is a wrapper around the [`useScriptGoogleMaps()`{lang="ts"}](/scripts/google-maps/api/use-script-google-maps){lang="ts"} composable. It provides a simple way to embed Google Maps in your Nuxt app.
+
+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).
+
+By default, it will load on the `mouseenter`, `mouseover`, and `mousedown` events.
+
+## Key Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | - | Google Maps API key |
+| `center` | `LatLngLiteral \| LatLng \| string` | - | Map center (coordinates or query string) |
+| `zoom` | `number` | `15` | Map zoom level (0-21). Reactive, takes precedence over `mapOptions.zoom` |
+| `mapOptions` | `google.maps.MapOptions` | - | Full map configuration |
+| `markers` | `(string \| AdvancedMarkerElementOptions)[]` | - | Quick markers (use SFC components for full control) |
+| `trigger` | `ElementScriptTrigger` | `['mouseenter', 'mouseover', 'mousedown']` | When to load the Google Maps script |
+| `aboveTheFold` | `boolean` | `false` | Prioritize placeholder image loading |
+
+See the [Facade Component API](/docs/guides/facade-components#facade-components-api) for all props, events, and slots.
+
+## Events
+
+The [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps){lang="html"} component emits a single `ready` event when Google Maps loads.
+
+The `ready` event payload contains:
+
+| Property | Type | Description |
+|---|---|---|
+| `googleMaps` | `Ref<typeof google.maps>`{lang="html"} | The Google Maps API namespace |
+| `map` | `ShallowRef<google.maps.Map>`{lang="html"} | The map instance |
+| `createAdvancedMapMarker` | `(options?) => Promise<AdvancedMarkerElement>`{lang="html"} | Create a marker programmatically |
+| `resolveQueryToLatLng` | `(query: string) => Promise<LatLng>`{lang="html"} | Geocode a location string |
+| `importLibrary` | `(key: string) => Promise<any>`{lang="html"} | Load an additional Google Maps library |
+
+To subscribe to Google Map events, you can use the `ready` event.
+
+```vue
+<script setup lang="ts">
+function handleReady({ map }: { map: ShallowRef<google.maps.Map | undefined> }) {
+  watch(map, (m) => {
+    if (!m)
+      return
+    m.addListener('center_changed', () => {
+      console.log('Center changed', m.getCenter())
+    })
+  }, { immediate: true })
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps @ready="handleReady" />
+</template>
+```
+
+## Slots
+
+The component provides minimal UI by default, only enough to be functional and accessible. There are a number of slots for you to customize the maps however you like.
+
+**default**
+
+The default slot displays content that will always be visible.
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <div class="absolute top-0 left-0 right-0 p-5 bg-white text-black">
+      <h1 class="text-xl font-bold">
+        My Custom Map
+      </h1>
+    </div>
+  </ScriptGoogleMaps>
+</template>
+```
+
+**awaitingLoad**
+
+Shown before the user triggers the map to load (e.g. before hover/click). Use this to show a call-to-action overlay on top of the static placeholder.
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #awaitingLoad>
+      <div class="bg-blue-500 text-white p-5">
+        Click to load the map!
+      </div>
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+**loading**
+
+Shown after the user triggers loading but before the map is interactive (script is being fetched/initialized).
+
+Note: This shows a `ScriptLoadingIndicator` by default for accessibility and UX, by providing a slot you will
+override this component. Make sure you provide a loading indicator.
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #loading>
+      <div class="bg-blue-500 text-white p-5">
+        Loading...
+      </div>
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
+
+**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.
+
+```vue
+<template>
+  <ScriptGoogleMaps>
+    <template #placeholder="{ placeholder }">
+      <img :src="placeholder">
+    </template>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/10.rectangle.md b/docs/content/scripts/google-maps/2.api/10.rectangle.md
new file mode 100644
index 00000000..74d4c04e
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/10.rectangle.md
@@ -0,0 +1,30 @@
+---
+title: <ScriptGoogleMapsRectangle>
+---
+
+Rectangular overlay on the map. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsRectangle"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsRectangle
+      :options="{
+        bounds: {
+          north: -34.387,
+          south: -34.407,
+          east: 150.664,
+          west: 150.624,
+        },
+        fillColor: '#00FF00',
+        fillOpacity: 0.25,
+        strokeWeight: 2,
+      }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/11.geojson.md b/docs/content/scripts/google-maps/2.api/11.geojson.md
new file mode 100644
index 00000000..578e8ebb
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/11.geojson.md
@@ -0,0 +1,60 @@
+---
+title: <ScriptGoogleMapsGeoJson>
+---
+
+Renders [GeoJSON](https://geojson.org/) data on the map using the Google Maps Data layer. Accepts a URL string or inline GeoJSON object. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsGeoJson"}
+::
+
+## Usage
+
+### Inline GeoJSON
+
+```vue
+<script setup lang="ts">
+const geoJsonData = {
+  type: 'FeatureCollection',
+  features: [
+    {
+      type: 'Feature',
+      geometry: {
+        type: 'Polygon',
+        coordinates: [[
+          [151.20, -33.87],
+          [151.25, -33.87],
+          [151.25, -33.90],
+          [151.20, -33.90],
+          [151.20, -33.87],
+        ]],
+      },
+      properties: { name: 'Sydney CBD' },
+    },
+  ],
+}
+</script>
+
+<template>
+  <ScriptGoogleMaps api-key="your-api-key" :center="{ lat: -33.885, lng: 151.225 }" :zoom="13">
+    <ScriptGoogleMapsGeoJson
+      :src="geoJsonData"
+      :style="{ fillColor: '#4285F4', fillOpacity: 0.3, strokeColor: '#4285F4', strokeWeight: 2 }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
+
+### Remote URL
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsGeoJson
+      src="https://example.com/boundaries.geojson"
+      :style="{ fillColor: '#34a853', fillOpacity: 0.2, strokeWeight: 1 }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
+
+Both `src` and `style` are reactive. Changing `src` clears existing features and loads the new data. Changing `style` updates feature styling in place.
diff --git a/docs/content/scripts/google-maps/2.api/12.heatmap-layer.md b/docs/content/scripts/google-maps/2.api/12.heatmap-layer.md
new file mode 100644
index 00000000..f7f6c2aa
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/12.heatmap-layer.md
@@ -0,0 +1,37 @@
+---
+title: <ScriptGoogleMapsHeatmapLayer>
+deprecated: true
+---
+
+Heatmap visualization layer. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component. The component automatically loads the `visualization` library.
+
+::callout{color="amber"}
+Google has deprecated `HeatmapLayer` (May 2025) and will remove it in May 2026. Consider using [deck.gl HeatmapLayer](https://deck.gl/docs/api-reference/aggregation-layers/heatmap-layer) as an alternative.
+::
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsHeatmapLayer"}
+::
+
+## Usage
+
+```vue
+<script setup lang="ts">
+const heatmapData = ref([
+  { lat: -34.397, lng: 150.644 },
+  { lat: -34.390, lng: 150.650 },
+  { lat: -34.395, lng: 150.640 },
+  { lat: -34.400, lng: 150.648 },
+])
+</script>
+
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsHeatmapLayer
+      :options="{
+        data: heatmapData,
+        radius: 20,
+      }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/13.overlay-view.md b/docs/content/scripts/google-maps/2.api/13.overlay-view.md
new file mode 100644
index 00000000..49f86c89
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/13.overlay-view.md
@@ -0,0 +1,99 @@
+---
+title: <ScriptGoogleMapsOverlayView>
+---
+
+Renders arbitrary Vue slot content at a map lat/lng position. Unlike `InfoWindow`, you have full control over HTML structure and styling.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsOverlayView"}
+::
+
+## Marker Anchoring
+
+When nested inside a `ScriptGoogleMapsMarker` or `ScriptGoogleMapsAdvancedMarkerElement`, the overlay automatically inherits the marker's position. This makes it a fully customizable alternative to `InfoWindow`, the overlay follows the marker when dragged.
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.397, lng: 150.644 }"
+      :options="{ gmpDraggable: true }"
+    >
+      <ScriptGoogleMapsOverlayView
+        anchor="bottom-center"
+        :offset="{ x: 0, y: -50 }"
+      >
+        <div class="custom-tooltip">
+          Fully custom content, no InfoWindow constraints
+        </div>
+      </ScriptGoogleMapsOverlayView>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
+
+## Popup on Marker Click
+
+Using `v-model:open` keeps the overlay mounted, toggling visibility via CSS. This avoids remount cost and preserves internal state.
+
+```vue
+<script setup lang="ts">
+const open = ref(false)
+</script>
+
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.397, lng: 150.644 }"
+      @click="open = !open"
+    >
+      <ScriptGoogleMapsOverlayView
+        v-model:open="open"
+        anchor="bottom-center"
+        :offset="{ x: 0, y: -50 }"
+      >
+        <div class="custom-popup">
+          <button @click.stop="open = false">
+            ×
+          </button>
+          <p>Any Vue content here</p>
+        </div>
+      </ScriptGoogleMapsOverlayView>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
+
+For simple cases where remounting is acceptable, `v-if` also works:
+
+```vue
+<ScriptGoogleMapsAdvancedMarkerElement
+  :position="{ lat: -34.397, lng: 150.644 }"
+  @click="open = true"
+>
+  <ScriptGoogleMapsOverlayView v-if="open">
+    <MyPopup @close="open = false" />
+  </ScriptGoogleMapsOverlayView>
+</ScriptGoogleMapsAdvancedMarkerElement>
+```
+
+## Persistent Label
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsOverlayView
+      :position="{ lat: -34.397, lng: 150.644 }"
+      anchor="center"
+      :block-map-interaction="false"
+    >
+      <span style="background: white; padding: 2px 6px; border-radius: 4px;">
+        Label text
+      </span>
+    </ScriptGoogleMapsOverlayView>
+  </ScriptGoogleMaps>
+</template>
+```
+
+::callout
+The `blockMapInteraction` prop (default `true`) calls `google.maps.OverlayView.preventMapHitsAndGesturesFrom()`{lang="ts"} to stop clicks, taps, and drags from propagating through the overlay to the map. Set it to `false` for non-interactive overlays like labels.
+::
diff --git a/docs/content/scripts/google-maps/2.api/14.use-script-google-maps.md b/docs/content/scripts/google-maps/2.api/14.use-script-google-maps.md
new file mode 100644
index 00000000..0ef72002
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/14.use-script-google-maps.md
@@ -0,0 +1,39 @@
+---
+title: useScriptGoogleMaps()
+---
+
+The [`useScriptGoogleMaps()`{lang="ts"}](/scripts/google-maps/api/use-script-google-maps){lang="ts"} composable lets you have fine-grained control over the Google Maps SDK. It provides a way to load the Google Maps SDK and interact with it programmatically.
+
+```ts
+export function useScriptGoogleMaps<T extends GoogleMapsApi>(_options?: GoogleMapsInput) {}
+```
+
+Please follow the [Registry Scripts](/docs/guides/registry-scripts) guide to learn more about advanced usage.
+
+## Example
+
+Loading the Google Maps SDK and interacting with it programmatically.
+
+```vue
+<script setup lang="ts">
+/// <reference types="google.maps" />
+const { onLoaded } = useScriptGoogleMaps({
+  apiKey: 'key'
+})
+const map = ref()
+onMounted(() => {
+  onLoaded(async (instance) => {
+    const maps = await instance.maps
+    const _map = new maps.Map(map.value, {
+      center: { lat: -34.397, lng: 150.644 },
+      zoom: 8
+    })
+    // Do something with the map
+  })
+})
+</script>
+
+<template>
+  <div ref="map" />
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/2.marker.md b/docs/content/scripts/google-maps/2.api/2.marker.md
new file mode 100644
index 00000000..eb4d5dd0
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/2.marker.md
@@ -0,0 +1,43 @@
+---
+title: <ScriptGoogleMapsMarker>
+---
+
+::callout{color="amber" icon="i-heroicons-exclamation-triangle"}
+`google.maps.Marker` is deprecated by Google. Use [`<ScriptGoogleMapsAdvancedMarkerElement>`{lang="html"}](/scripts/google-maps/api/advanced-marker-element) instead for new projects.
+::
+
+Classic map marker with icon support. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsMarker"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsMarker
+      :position="{ lat: -34.397, lng: 150.644 }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
+
+### With Info Window
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsMarker
+      :position="{ lat: -34.397, lng: 150.644 }"
+    >
+      <ScriptGoogleMapsInfoWindow>
+        <div>
+          <h3>Sydney, Australia</h3>
+          <p>A great city!</p>
+        </div>
+      </ScriptGoogleMapsInfoWindow>
+    </ScriptGoogleMapsMarker>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/3.advanced-marker-element.md b/docs/content/scripts/google-maps/2.api/3.advanced-marker-element.md
new file mode 100644
index 00000000..c7bcb823
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/3.advanced-marker-element.md
@@ -0,0 +1,70 @@
+---
+title: <ScriptGoogleMapsAdvancedMarkerElement>
+---
+
+Modern advanced marker with HTML content support. This is the recommended marker type. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsAdvancedMarkerElement"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.407, lng: 150.654 }"
+    >
+      <ScriptGoogleMapsPinElement
+        :options="{ scale: 1.5, background: '#FF0000' }"
+      />
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
+
+### Custom Marker Content
+
+The `#content` slot replaces the default pin with any HTML or Vue content. The slot content becomes the marker's visual on the map.
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.397, lng: 150.644 }"
+    >
+      <template #content>
+        <div style="background: #34a853; color: white; padding: 4px 10px; border-radius: 16px; font-weight: bold;">
+          $420k
+        </div>
+      </template>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
+
+::callout
+Use `ScriptGoogleMapsPinElement` if you only need to customize colors or glyph while keeping the pin shape. The `#content` slot replaces the marker entirely. If you use both, `PinElement` takes precedence.
+::
+
+### With Custom Overlay
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.397, lng: 150.644 }"
+      :options="{ gmpDraggable: true }"
+    >
+      <ScriptGoogleMapsOverlayView
+        anchor="bottom-center"
+        :offset="{ x: 0, y: -50 }"
+      >
+        <div class="custom-tooltip">
+          Fully custom content, no InfoWindow constraints
+        </div>
+      </ScriptGoogleMapsOverlayView>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/4.pin-element.md b/docs/content/scripts/google-maps/2.api/4.pin-element.md
new file mode 100644
index 00000000..11522e81
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/4.pin-element.md
@@ -0,0 +1,29 @@
+---
+title: <ScriptGoogleMapsPinElement>
+---
+
+Customizable pin marker. Place as a child of [`<ScriptGoogleMapsAdvancedMarkerElement>`{lang="html"}](/scripts/google-maps/api/advanced-marker-element).
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsPinElement"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.407, lng: 150.654 }"
+    >
+      <ScriptGoogleMapsPinElement
+        :options="{
+          scale: 1.5,
+          background: '#FF0000',
+          borderColor: '#CC0000',
+          glyphColor: '#FFFFFF',
+        }"
+      />
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/5.info-window.md b/docs/content/scripts/google-maps/2.api/5.info-window.md
new file mode 100644
index 00000000..b7de4b5a
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/5.info-window.md
@@ -0,0 +1,27 @@
+---
+title: <ScriptGoogleMapsInfoWindow>
+---
+
+Information window that automatically opens on parent marker click. Place as a child of [`<ScriptGoogleMapsMarker>`{lang="html"}](/scripts/google-maps/api/marker) or [`<ScriptGoogleMapsAdvancedMarkerElement>`{lang="html"}](/scripts/google-maps/api/advanced-marker-element).
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsInfoWindow"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -34.397, lng: 150.644 }"
+    >
+      <ScriptGoogleMapsInfoWindow>
+        <div>
+          <h3>Sydney, Australia</h3>
+          <p>A great city!</p>
+        </div>
+      </ScriptGoogleMapsInfoWindow>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/6.marker-clusterer.md b/docs/content/scripts/google-maps/2.api/6.marker-clusterer.md
new file mode 100644
index 00000000..5a3bcbd1
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/6.marker-clusterer.md
@@ -0,0 +1,38 @@
+---
+title: <ScriptGoogleMapsMarkerClusterer>
+---
+
+Groups nearby markers into clusters for cleaner map visualization at lower zoom levels. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsMarkerClusterer"}
+::
+
+## Installation
+
+Requires the `@googlemaps/markerclusterer` peer dependency:
+
+```bash
+pnpm add @googlemaps/markerclusterer
+```
+
+## Usage
+
+Child markers register and unregister themselves automatically.
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsMarkerClusterer>
+      <ScriptGoogleMapsAdvancedMarkerElement
+        v-for="location in locations"
+        :key="location.id"
+        :position="location.position"
+      >
+        <ScriptGoogleMapsInfoWindow>
+          <div>{{ location.name }}</div>
+        </ScriptGoogleMapsInfoWindow>
+      </ScriptGoogleMapsAdvancedMarkerElement>
+    </ScriptGoogleMapsMarkerClusterer>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/7.circle.md b/docs/content/scripts/google-maps/2.api/7.circle.md
new file mode 100644
index 00000000..93d93803
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/7.circle.md
@@ -0,0 +1,28 @@
+---
+title: <ScriptGoogleMapsCircle>
+---
+
+Circular overlay on the map. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsCircle"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsCircle
+      :options="{
+        center: { lat: -34.397, lng: 150.644 },
+        radius: 1000,
+        fillColor: '#FF0000',
+        fillOpacity: 0.35,
+        strokeColor: '#FF0000',
+        strokeOpacity: 0.8,
+        strokeWeight: 2,
+      }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/8.polygon.md b/docs/content/scripts/google-maps/2.api/8.polygon.md
new file mode 100644
index 00000000..ca5414f3
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/8.polygon.md
@@ -0,0 +1,29 @@
+---
+title: <ScriptGoogleMapsPolygon>
+---
+
+Polygon shape overlay on the map. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsPolygon"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsPolygon
+      :options="{
+        paths: [
+          { lat: -34.397, lng: 150.644 },
+          { lat: -34.407, lng: 150.654 },
+          { lat: -34.417, lng: 150.634 },
+        ],
+        fillColor: '#0000FF',
+        fillOpacity: 0.3,
+        strokeWeight: 2,
+      }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/2.api/9.polyline.md b/docs/content/scripts/google-maps/2.api/9.polyline.md
new file mode 100644
index 00000000..499029df
--- /dev/null
+++ b/docs/content/scripts/google-maps/2.api/9.polyline.md
@@ -0,0 +1,29 @@
+---
+title: <ScriptGoogleMapsPolyline>
+---
+
+Line path overlay on the map. Place inside a [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps) component.
+
+::script-types{script-key="google-maps" filter="ScriptGoogleMapsPolyline"}
+::
+
+## Usage
+
+```vue
+<template>
+  <ScriptGoogleMaps api-key="your-api-key">
+    <ScriptGoogleMapsPolyline
+      :options="{
+        path: [
+          { lat: -34.397, lng: 150.644 },
+          { lat: -34.407, lng: 150.654 },
+          { lat: -34.417, lng: 150.634 },
+        ],
+        strokeColor: '#FF0000',
+        strokeOpacity: 1.0,
+        strokeWeight: 3,
+      }"
+    />
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/docs/content/scripts/google-maps/index.md b/docs/content/scripts/google-maps/index.md
new file mode 100644
index 00000000..848229c5
--- /dev/null
+++ b/docs/content/scripts/google-maps/index.md
@@ -0,0 +1,227 @@
+---
+title: Google Maps
+description: Show performance-optimized Google Maps in your Nuxt app.
+links:
+  - label: useScriptGoogleMaps
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/scripts/blob/main/src/runtime/registry/google-maps.ts
+    size: xs
+  - label: "<ScriptGoogleMaps>"
+    icon: i-simple-icons-github
+    to: https://github.com/nuxt/scripts/blob/main/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
+    size: xs
+---
+
+[Google Maps](https://maps.google.com/) allows you to embed maps in your website and customize them with your content.
+
+Nuxt Scripts provides a [`useScriptGoogleMaps()`{lang="ts"}](/scripts/google-maps/api/use-script-google-maps){lang="ts"} composable and a headless [`<ScriptGoogleMaps>`{lang="html"}](/scripts/google-maps/api/script-google-maps){lang="html"} component to interact with the Google Maps.
+
+::script-types{exclude-components}
+::
+
+## Types
+
+To use Google Maps with full TypeScript support, you will need
+to install the `@types/google.maps` dependency.
+
+```bash
+pnpm add -D @types/google.maps
+```
+
+## Setup
+
+Enable Google Maps in your `nuxt.config` and provide your API key via environment variable:
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  scripts: {
+    registry: {
+      googleMaps: true,
+    },
+  },
+  runtimeConfig: {
+    public: {
+      scripts: {
+        googleMaps: {
+          apiKey: '', // NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY
+        },
+      },
+    },
+  },
+})
+```
+
+```text [.env]
+NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY=<YOUR_API_KEY>
+```
+
+You must add this. It registers server proxy routes that keep your API key server-side:
+- `/_scripts/proxy/google-static-maps` for placeholder images
+- `/_scripts/proxy/google-maps-geocode` for location search
+
+::callout{color="amber"}
+You can pass `api-key` directly on the `<ScriptGoogleMaps>`{lang="html"} component, but this approach is not recommended, as it exposes your key in client-side requests.
+::
+
+See [Billing & Permissions](/scripts/google-maps/guides/billing) for API costs and required permissions.
+
+## Demo
+
+::code-group
+
+:google-maps-demo{label="Output"}
+
+```vue [Input]
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const isLoaded = ref(false)
+const center = ref()
+const maps = ref()
+
+const query = ref({
+  lat: -37.7995487,
+  lng: 144.9867841,
+})
+
+const markers = ref([])
+
+let increment = 1
+function addMarker() {
+  // push to markers, we want to add a marker from the center but randomize the position by a bit
+  const _center = center.value || query.value
+  // lat and lng may be a function
+  const _lat = typeof _center.lat === 'function' ? _center.lat() : _center.lat
+  const _lng = typeof _center.lng === 'function' ? _center.lng() : _center.lng
+  const lat = (1000 * _lat + increment) / 1000
+  const lng = (1000 * _lng + increment) / 1000
+  increment += 1
+
+  markers.value.push(`${lat},${lng}`)
+}
+
+function removeMarkers() {
+  markers.value = []
+  increment = 1
+}
+function handleReady({ map }) {
+  center.value = map.value.getCenter()
+  map.value.addListener('center_changed', () => {
+    center.value = map.value.getCenter()
+  })
+  isLoaded.value = true
+}
+</script>
+
+<template>
+  <div class="not-prose">
+    <div class="flex items-center justify-center p-5">
+      <ScriptGoogleMaps
+        ref="maps"
+        :center="query"
+        :markers="markers"
+        api-key="YOUR_API_KEY"
+        class="group"
+        above-the-fold
+        @ready="handleReady"
+      />
+    </div>
+    <div class="text-center">
+      <UAlert v-if="!isLoaded" class="mb-5" size="sm" color="blue" variant="soft" title="Static Image: Hover to load interactive" description="Hovering the map will trigger the Google Maps script to load and init the map." />
+      <UAlert v-if="isLoaded" class="mb-5" size="sm" color="blue" variant="soft" title="Interactive Map">
+        <template #description>
+          Center: {{ center }}
+        </template>
+      </UAlert>
+      <UButton type="button" class="" @click="addMarker">
+        Add Marker
+      </UButton>
+      <UButton v-if="markers.length" type="button" color="gray" variant="ghost" class="" @click="removeMarkers">
+        Remove Markers
+      </UButton>
+    </div>
+  </div>
+</template>
+```
+
+::
+
+## Quick Start
+
+### Minimal Map
+
+```vue
+<template>
+  <ScriptGoogleMaps
+    :center="{ lat: -33.8688, lng: 151.2093 }"
+    :zoom="12"
+  />
+</template>
+```
+
+### Markers with Info Windows
+
+```vue
+<template>
+  <ScriptGoogleMaps :center="{ lat: -33.8688, lng: 151.2093 }" :zoom="12">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -33.8688, lng: 151.2093 }"
+    >
+      <ScriptGoogleMapsInfoWindow>
+        <h3>Sydney Opera House</h3>
+        <p>Iconic performing arts venue</p>
+      </ScriptGoogleMapsInfoWindow>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
+
+### Custom Marker Content
+
+The `#content` slot replaces the default pin with any Vue template.
+
+```vue
+<template>
+  <ScriptGoogleMaps :center="{ lat: -33.8688, lng: 151.2093 }" :zoom="12">
+    <ScriptGoogleMapsAdvancedMarkerElement :position="{ lat: -33.8688, lng: 151.2093 }">
+      <template #content>
+        <div style="background: #1a73e8; color: white; padding: 4px 10px; border-radius: 16px; font-weight: bold;">
+          $1.2M
+        </div>
+      </template>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
+
+### Custom Popups
+
+`ScriptGoogleMapsOverlayView` gives full control over popup styling. Use `v-model:open` to toggle without remounting.
+
+```vue
+<script setup lang="ts">
+const showPopup = ref(false)
+</script>
+
+<template>
+  <ScriptGoogleMaps :center="{ lat: -33.8688, lng: 151.2093 }" :zoom="12">
+    <ScriptGoogleMapsAdvancedMarkerElement
+      :position="{ lat: -33.8688, lng: 151.2093 }"
+      @click="showPopup = !showPopup"
+    >
+      <ScriptGoogleMapsOverlayView
+        v-model:open="showPopup"
+        anchor="bottom-center"
+        :offset="{ x: 0, y: -50 }"
+      >
+        <div class="popup">
+          <p>Any Vue content, fully styled</p>
+          <button @click.stop="showPopup = false">
+            Close
+          </button>
+        </div>
+      </ScriptGoogleMapsOverlayView>
+    </ScriptGoogleMapsAdvancedMarkerElement>
+  </ScriptGoogleMaps>
+</template>
+```
diff --git a/playground/pages/third-parties/google-maps/sfcs.vue b/playground/pages/third-parties/google-maps/sfcs.vue
index 3fd79955..79b6d620 100644
--- a/playground/pages/third-parties/google-maps/sfcs.vue
+++ b/playground/pages/third-parties/google-maps/sfcs.vue
@@ -58,6 +58,19 @@ const geoJsonData = {
   ],
 }
 
+const isOverlayViewShown = ref(false)
+
+const isOverlayViewOnMarkerShown = ref(false)
+
+const isOverlayViewOnAdvancedMarkerShown = ref(false)
+
+const isCustomMarkerContentShown = ref(false)
+
+const isOverlayPopupShown = ref(false)
+const overlayPopupOpen = ref(false)
+
+const zoom = ref(8)
+
 const googleMapsRef = useTemplateRef('googleMapsRef')
 
 whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
@@ -88,9 +101,9 @@ whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
       :width="1280"
       :height="720"
       above-the-fold
+      :zoom="zoom"
       :map-options="{
         center: { lat: -34.397, lng: 150.644 },
-        zoom: 8,
         mapId: 'DEMO_MAP_ID',
       }"
     >
@@ -224,6 +237,80 @@ whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
         }"
       />
 
+      <ScriptGoogleMapsOverlayView
+        v-if="isOverlayViewShown"
+        :position="{ lat: -33.8688, lng: 151.2093 }"
+        anchor="bottom-center"
+        :offset="{ x: 0, y: -10 }"
+      >
+        <div style="background: white; padding: 8px 12px; border-radius: 8px; box-shadow: 0 2px 6px rgba(0,0,0,0.3); font-family: sans-serif;">
+          <strong>Custom Overlay</strong>
+          <p style="margin: 4px 0 0;">Vue slot content with full reactivity</p>
+        </div>
+      </ScriptGoogleMapsOverlayView>
+
+      <ScriptGoogleMapsMarker
+        v-if="isOverlayViewOnMarkerShown"
+        :options="{ position: { lat: -34.0, lng: 150.8 }, draggable: true }"
+      >
+        <ScriptGoogleMapsOverlayView
+          anchor="bottom-center"
+          :offset="{ x: 0, y: -40 }"
+        >
+          <div style="background: #1a73e8; color: white; padding: 6px 12px; border-radius: 20px; font-family: sans-serif; font-size: 13px; white-space: nowrap; box-shadow: 0 2px 6px rgba(0,0,0,0.3);">
+            Drag me! Custom overlay on Marker
+          </div>
+        </ScriptGoogleMapsOverlayView>
+      </ScriptGoogleMapsMarker>
+
+      <ScriptGoogleMapsAdvancedMarkerElement
+        v-if="isOverlayViewOnAdvancedMarkerShown"
+        :options="{ position: { lat: -34.2, lng: 150.9 }, gmpDraggable: true }"
+      >
+        <ScriptGoogleMapsOverlayView
+          anchor="bottom-center"
+          :offset="{ x: 0, y: -50 }"
+        >
+          <div style="background: #ea4335; color: white; padding: 8px 16px; border-radius: 8px; font-family: sans-serif; font-size: 13px; white-space: nowrap; box-shadow: 0 2px 8px rgba(0,0,0,0.3);">
+            <strong>Custom tooltip</strong>
+            <div style="font-size: 11px; opacity: 0.9;">OverlayView on AdvancedMarker</div>
+          </div>
+        </ScriptGoogleMapsOverlayView>
+      </ScriptGoogleMapsAdvancedMarkerElement>
+
+      <!-- Custom marker content via #content slot -->
+      <ScriptGoogleMapsAdvancedMarkerElement
+        v-if="isCustomMarkerContentShown"
+        :options="{ position: { lat: -34.5, lng: 150.7 } }"
+      >
+        <template #content>
+          <div style="background: #34a853; color: white; padding: 4px 10px; border-radius: 16px; font-family: sans-serif; font-size: 12px; font-weight: bold; box-shadow: 0 2px 6px rgba(0,0,0,0.3); cursor: pointer;">
+            $420k
+          </div>
+        </template>
+      </ScriptGoogleMapsAdvancedMarkerElement>
+
+      <!-- OverlayView with v-model:open (click marker to toggle popup) -->
+      <ScriptGoogleMapsAdvancedMarkerElement
+        v-if="isOverlayPopupShown"
+        :options="{ position: { lat: -34.3, lng: 151.0 } }"
+        @click="overlayPopupOpen = !overlayPopupOpen"
+      >
+        <ScriptGoogleMapsOverlayView
+          v-model:open="overlayPopupOpen"
+          anchor="bottom-center"
+          :offset="{ x: 0, y: -50 }"
+        >
+          <div style="background: white; padding: 12px 16px; border-radius: 8px; box-shadow: 0 2px 8px rgba(0,0,0,0.3); font-family: sans-serif; font-size: 13px; min-width: 150px;">
+            <strong>Custom Popup</strong>
+            <p style="margin: 4px 0 0; color: #666;">v-model:open, no remount</p>
+            <button style="margin-top: 8px; background: #ea4335; color: white; border: none; padding: 4px 12px; border-radius: 4px; cursor: pointer;" @click.stop="overlayPopupOpen = false">
+              Close
+            </button>
+          </div>
+        </ScriptGoogleMapsOverlayView>
+      </ScriptGoogleMapsAdvancedMarkerElement>
+
       <ScriptGoogleMapsCircle
         v-if="isCircleShown"
         :options="{
@@ -309,12 +396,58 @@ whenever(() => googleMapsRef.value?.googleMaps, (googleMaps) => {
         {{ `${isGeoJsonShown ? 'Hide' : 'Show'} geojson` }}
       </button>
 
+      <button
+        class="bg-[#ffa500] rounded-lg px-2 py-1"
+        @click="isOverlayViewShown = !isOverlayViewShown"
+      >
+        {{ `${isOverlayViewShown ? 'Hide' : 'Show'} overlay view` }}
+      </button>
+
+      <button
+        class="bg-[#ffa500] rounded-lg px-2 py-1"
+        @click="isOverlayViewOnMarkerShown = !isOverlayViewOnMarkerShown"
+      >
+        {{ `${isOverlayViewOnMarkerShown ? 'Hide' : 'Show'} overlay on marker` }}
+      </button>
+
+      <button
+        class="bg-[#ffa500] rounded-lg px-2 py-1"
+        @click="isOverlayViewOnAdvancedMarkerShown = !isOverlayViewOnAdvancedMarkerShown"
+      >
+        {{ `${isOverlayViewOnAdvancedMarkerShown ? 'Hide' : 'Show'} overlay on advanced marker` }}
+      </button>
+
+      <button
+        class="bg-[#ffa500] rounded-lg px-2 py-1"
+        @click="isCustomMarkerContentShown = !isCustomMarkerContentShown"
+      >
+        {{ `${isCustomMarkerContentShown ? 'Hide' : 'Show'} custom marker content` }}
+      </button>
+
+      <button
+        class="bg-[#ffa500] rounded-lg px-2 py-1"
+        @click="isOverlayPopupShown = !isOverlayPopupShown"
+      >
+        {{ `${isOverlayPopupShown ? 'Hide' : 'Show'} overlay popup (v-model:open)` }}
+      </button>
+
       <button
         class="bg-[#ffa500] rounded-lg px-2 py-1"
         @click="isCircleShown = !isCircleShown"
       >
         {{ `${isCircleShown ? 'Hide' : 'Show'} circle` }}
       </button>
+
+      <div class="flex items-center gap-2">
+        <label>Zoom: {{ zoom }}</label>
+        <input
+          v-model.number="zoom"
+          type="range"
+          min="1"
+          max="20"
+          class="w-32"
+        >
+      </div>
     </div>
   </div>
 </template>
diff --git a/scripts/generate-registry-types.ts b/scripts/generate-registry-types.ts
index 2af5a242..1f22b971 100644
--- a/scripts/generate-registry-types.ts
+++ b/scripts/generate-registry-types.ts
@@ -13,11 +13,6 @@ interface ExtractedDeclaration {
   code: string
 }
 
-interface ExtractedProps {
-  code: string
-  defaults: Record<string, string>
-}
-
 // --- Helpers ---
 
 function getName(node: any): string | null {
@@ -549,6 +544,8 @@ const componentToSlug: Record<string, string> = {
   ScriptGoogleMapsPolygon: 'google-maps',
   ScriptGoogleMapsPolyline: 'google-maps',
   ScriptGoogleMapsRectangle: 'google-maps',
+  ScriptGoogleMapsOverlayView: 'google-maps',
+  ScriptGoogleMapsGeoJson: 'google-maps',
   ScriptCarbonAds: 'carbon-ads',
   ScriptCrisp: 'crisp',
   ScriptIntercom: 'intercom',
diff --git a/src/registry-types.json b/src/registry-types.json
index a87a611f..adab2f46 100644
--- a/src/registry-types.json
+++ b/src/registry-types.json
@@ -202,7 +202,7 @@
       {
         "name": "ScriptGoogleMapsAdvancedMarkerElementEvents",
         "kind": "interface",
-        "code": "interface ScriptGoogleMapsAdvancedMarkerElementEvents {\n  animation_changed: -\n  clickable_changed: -\n  cursor_changed: -\n  draggable_changed: -\n  flat_changed: -\n  icon_changed: -\n  position_changed: -\n  shape_changed: -\n  title_changed: -\n  visible_changed: -\n  zindex_changed: -\n  click: google.maps.MapMouseEvent\n  contextmenu: google.maps.MapMouseEvent\n  dblclick: google.maps.MapMouseEvent\n  drag: google.maps.MapMouseEvent\n  dragend: google.maps.MapMouseEvent\n  dragstart: google.maps.MapMouseEvent\n  mousedown: google.maps.MapMouseEvent\n  mouseout: google.maps.MapMouseEvent\n  mouseover: google.maps.MapMouseEvent\n  mouseup: google.maps.MapMouseEvent\n}"
+        "code": "interface ScriptGoogleMapsAdvancedMarkerElementEvents {\n  click: google.maps.MapMouseEvent\n  drag: google.maps.MapMouseEvent\n  dragend: google.maps.MapMouseEvent\n  dragstart: google.maps.MapMouseEvent\n}"
       },
       {
         "name": "ScriptGoogleMapsCircleProps",
@@ -214,6 +214,16 @@
         "kind": "interface",
         "code": "interface ScriptGoogleMapsCircleEvents {\n  center_changed: -\n  radius_changed: -\n  click: google.maps.MapMouseEvent\n  dblclick: google.maps.MapMouseEvent\n  drag: google.maps.MapMouseEvent\n  dragend: google.maps.MapMouseEvent\n  dragstart: google.maps.MapMouseEvent\n  mousedown: google.maps.MapMouseEvent\n  mousemove: google.maps.MapMouseEvent\n  mouseout: google.maps.MapMouseEvent\n  mouseover: google.maps.MapMouseEvent\n  mouseup: google.maps.MapMouseEvent\n  rightclick: google.maps.MapMouseEvent\n}"
       },
+      {
+        "name": "ScriptGoogleMapsGeoJsonProps",
+        "kind": "interface",
+        "code": "interface ScriptGoogleMapsGeoJsonProps {\n  src: string | object\n  style?: google.maps.Data.StylingFunction | google.maps.Data.StyleOptions\n}"
+      },
+      {
+        "name": "ScriptGoogleMapsGeoJsonEvents",
+        "kind": "interface",
+        "code": "interface ScriptGoogleMapsGeoJsonEvents {\n  click: google.maps.Data.MouseEvent\n  contextmenu: google.maps.Data.MouseEvent\n  dblclick: google.maps.Data.MouseEvent\n  mousedown: google.maps.Data.MouseEvent\n  mousemove: google.maps.Data.MouseEvent\n  mouseout: google.maps.Data.MouseEvent\n  mouseover: google.maps.Data.MouseEvent\n  mouseup: google.maps.Data.MouseEvent\n  addfeature: google.maps.Data.AddFeatureEvent\n  removefeature: google.maps.Data.RemoveFeatureEvent\n  setgeometry: google.maps.Data.SetGeometryEvent\n  setproperty: google.maps.Data.SetPropertyEvent\n  removeproperty: google.maps.Data.RemovePropertyEvent\n}"
+      },
       {
         "name": "ScriptGoogleMapsHeatmapLayerProps",
         "kind": "interface",
@@ -2116,57 +2126,41 @@
     ],
     "ScriptGoogleMapsAdvancedMarkerElementEvents": [
       {
-        "name": "animation_changed",
-        "type": "-",
-        "required": false
-      },
-      {
-        "name": "clickable_changed",
-        "type": "-",
-        "required": false
-      },
-      {
-        "name": "cursor_changed",
-        "type": "-",
-        "required": false
-      },
-      {
-        "name": "draggable_changed",
-        "type": "-",
-        "required": false
-      },
-      {
-        "name": "flat_changed",
-        "type": "-",
+        "name": "click",
+        "type": "google.maps.MapMouseEvent",
         "required": false
       },
       {
-        "name": "icon_changed",
-        "type": "-",
+        "name": "drag",
+        "type": "google.maps.MapMouseEvent",
         "required": false
       },
       {
-        "name": "position_changed",
-        "type": "-",
+        "name": "dragend",
+        "type": "google.maps.MapMouseEvent",
         "required": false
       },
       {
-        "name": "shape_changed",
-        "type": "-",
+        "name": "dragstart",
+        "type": "google.maps.MapMouseEvent",
         "required": false
-      },
+      }
+    ],
+    "ScriptGoogleMapsCircleProps": [
       {
-        "name": "title_changed",
-        "type": "-",
+        "name": "options",
+        "type": "Omit<google.maps.CircleOptions, 'map'>",
         "required": false
-      },
+      }
+    ],
+    "ScriptGoogleMapsCircleEvents": [
       {
-        "name": "visible_changed",
+        "name": "center_changed",
         "type": "-",
         "required": false
       },
       {
-        "name": "zindex_changed",
+        "name": "radius_changed",
         "type": "-",
         "required": false
       },
@@ -2175,11 +2169,6 @@
         "type": "google.maps.MapMouseEvent",
         "required": false
       },
-      {
-        "name": "contextmenu",
-        "type": "google.maps.MapMouseEvent",
-        "required": false
-      },
       {
         "name": "dblclick",
         "type": "google.maps.MapMouseEvent",
@@ -2205,6 +2194,11 @@
         "type": "google.maps.MapMouseEvent",
         "required": false
       },
+      {
+        "name": "mousemove",
+        "type": "google.maps.MapMouseEvent",
+        "required": false
+      },
       {
         "name": "mouseout",
         "type": "google.maps.MapMouseEvent",
@@ -2219,79 +2213,89 @@
         "name": "mouseup",
         "type": "google.maps.MapMouseEvent",
         "required": false
+      },
+      {
+        "name": "rightclick",
+        "type": "google.maps.MapMouseEvent",
+        "required": false
       }
     ],
-    "ScriptGoogleMapsCircleProps": [
+    "ScriptGoogleMapsGeoJsonProps": [
       {
-        "name": "options",
-        "type": "Omit<google.maps.CircleOptions, 'map'>",
+        "name": "src",
+        "type": "string | object",
+        "required": true
+      },
+      {
+        "name": "style",
+        "type": "google.maps.Data.StylingFunction | google.maps.Data.StyleOptions",
         "required": false
       }
     ],
-    "ScriptGoogleMapsCircleEvents": [
+    "ScriptGoogleMapsGeoJsonEvents": [
       {
-        "name": "center_changed",
-        "type": "-",
+        "name": "click",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "radius_changed",
-        "type": "-",
+        "name": "contextmenu",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "click",
-        "type": "google.maps.MapMouseEvent",
+        "name": "dblclick",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "dblclick",
-        "type": "google.maps.MapMouseEvent",
+        "name": "mousedown",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "drag",
-        "type": "google.maps.MapMouseEvent",
+        "name": "mousemove",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "dragend",
-        "type": "google.maps.MapMouseEvent",
+        "name": "mouseout",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "dragstart",
-        "type": "google.maps.MapMouseEvent",
+        "name": "mouseover",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "mousedown",
-        "type": "google.maps.MapMouseEvent",
+        "name": "mouseup",
+        "type": "google.maps.Data.MouseEvent",
         "required": false
       },
       {
-        "name": "mousemove",
-        "type": "google.maps.MapMouseEvent",
+        "name": "addfeature",
+        "type": "google.maps.Data.AddFeatureEvent",
         "required": false
       },
       {
-        "name": "mouseout",
-        "type": "google.maps.MapMouseEvent",
+        "name": "removefeature",
+        "type": "google.maps.Data.RemoveFeatureEvent",
         "required": false
       },
       {
-        "name": "mouseover",
-        "type": "google.maps.MapMouseEvent",
+        "name": "setgeometry",
+        "type": "google.maps.Data.SetGeometryEvent",
         "required": false
       },
       {
-        "name": "mouseup",
-        "type": "google.maps.MapMouseEvent",
+        "name": "setproperty",
+        "type": "google.maps.Data.SetPropertyEvent",
         "required": false
       },
       {
-        "name": "rightclick",
-        "type": "google.maps.MapMouseEvent",
+        "name": "removeproperty",
+        "type": "google.maps.Data.RemovePropertyEvent",
         "required": false
       }
     ],
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
index e0d6cd90..03f4d3b6 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMaps.vue
@@ -57,6 +57,11 @@ const props = withDefaults(defineProps<{
    * A latitude / longitude of where to focus the map.
    */
   center?: google.maps.LatLng | google.maps.LatLngLiteral | `${string},${string}`
+  /**
+   * Zoom level for the map (0-21). Reactive: changing this will update the map.
+   * Takes precedence over mapOptions.zoom when provided.
+   */
+  zoom?: number
   /**
    * Should a marker be displayed on the map where the centre is.
    */
@@ -152,8 +157,12 @@ const currentMapId = computed(() => {
 
 const mapsApi = ref<typeof google.maps | undefined>()
 
-if (import.meta.dev && !apiKey)
-  throw new Error('GoogleMaps requires an API key. Please provide `apiKey` on the <ScriptGoogleMaps> or globally via `runtimeConfig.public.scripts.googleMaps.apiKey`.')
+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')
+}
 
 // TODO allow a null center may need to be resolved via an API function
 
@@ -175,7 +184,7 @@ const { load, status, onLoaded } = useScriptGoogleMaps({
 
 const options = computed(() => {
   const mapId = props.mapOptions?.styles ? undefined : (currentMapId.value || 'map')
-  return defu({ center: centerOverride.value, mapId }, props.mapOptions, {
+  return defu({ center: centerOverride.value, mapId, zoom: props.zoom }, props.mapOptions, {
     center: props.center,
     zoom: 15,
   })
@@ -236,7 +245,7 @@ async function createAdvancedMapMarker(_options?: google.maps.marker.AdvancedMar
 
 const queryToLatLngCache = new Map<string, google.maps.LatLng | google.maps.LatLngLiteral>()
 
-async function resolveQueryToLatLang(query: string) {
+async function resolveQueryToLatLng(query: string) {
   if (query && typeof query === 'object')
     return Promise.resolve(query)
   if (queryToLatLngCache.has(query)) {
@@ -319,7 +328,7 @@ const googleMaps = {
   googleMaps: mapsApi,
   map,
   createAdvancedMapMarker,
-  resolveQueryToLatLang,
+  resolveQueryToLatLng,
   importLibrary,
 } as const
 
@@ -383,7 +392,7 @@ onMounted(() => {
     if (center) {
       if (isLocationQuery(center) && ready.value) {
         // need to resolve center from query
-        center = await resolveQueryToLatLang(center as string)
+        center = await resolveQueryToLatLng(center as string)
       }
       map.value!.setCenter(center as google.maps.LatLng)
       if (props.centerMarker) {
@@ -418,7 +427,7 @@ onMounted(() => {
     map.value = new mapsApi.value!.Map(mapEl.value!, _options)
     if (center && isLocationQuery(center)) {
       // need to resolve center
-      centerOverride.value = await resolveQueryToLatLang(center)
+      centerOverride.value = await resolveQueryToLatLng(center)
       map.value?.setCenter(centerOverride.value)
     }
     ready.value = true
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue
index b13fd3a4..166b730e 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsAdvancedMarkerElement.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
-import { inject, provide, watch } from 'vue'
+import { inject, provide, useSlots, useTemplateRef, watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { ADVANCED_MARKER_ELEMENT_INJECTION_KEY } from './injectionKeys'
 import { MARKER_CLUSTERER_INJECTION_KEY } from './ScriptGoogleMapsMarkerClusterer.vue'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
@@ -9,6 +10,7 @@ export { ADVANCED_MARKER_ELEMENT_INJECTION_KEY } from './injectionKeys'
 
 <script setup lang="ts">
 const props = defineProps<{
+  position?: google.maps.LatLngLiteral | google.maps.LatLng
   options?: Omit<google.maps.marker.AdvancedMarkerElementOptions, 'map'>
 }>()
 
@@ -17,40 +19,40 @@ const emit = defineEmits<{
   (event: typeof eventsWithMapMouseEventPayload[number], payload: google.maps.MapMouseEvent): void
 }>()
 
-const eventsWithoutPayload = [
-  'animation_changed',
-  'clickable_changed',
-  'cursor_changed',
-  'draggable_changed',
-  'flat_changed',
-  'icon_changed',
-  'position_changed',
-  'shape_changed',
-  'title_changed',
-  'visible_changed',
-  'zindex_changed',
-] as const
+// AdvancedMarkerElement supported events only
+// See https://developers.google.com/maps/documentation/javascript/reference/advanced-markers
+const eventsWithoutPayload = [] as const
 
 const eventsWithMapMouseEventPayload = [
   'click',
-  'contextmenu',
-  'dblclick',
   'drag',
   'dragend',
   'dragstart',
-  'mousedown',
-  'mouseout',
-  'mouseover',
-  'mouseup',
 ] as const
 
+const slots = useSlots()
+const markerContent = useTemplateRef('marker-content')
 const markerClustererContext = inject(MARKER_CLUSTERER_INJECTION_KEY, undefined)
 
 const advancedMarkerElement = useGoogleMapsResource<google.maps.marker.AdvancedMarkerElement>({
+  ready: () => !slots.content || !!markerContent.value,
   async create({ mapsApi, map }) {
     await mapsApi.importLibrary('marker')
-    const marker = new mapsApi.marker.AdvancedMarkerElement(props.options)
-    setupEventListeners(marker)
+    const marker = new mapsApi.marker.AdvancedMarkerElement({
+      ...props.options,
+      ...(props.position ? { position: props.position } : {}),
+    })
+
+    // Use #content slot as marker visual if provided
+    if (markerContent.value) {
+      marker.content = markerContent.value
+    }
+
+    bindGoogleMapsEvents(marker, emit, {
+      noPayload: eventsWithoutPayload,
+      withPayload: eventsWithMapMouseEventPayload,
+    })
+
     if (markerClustererContext?.markerClusterer.value) {
       markerClustererContext.markerClusterer.value.addMarker(marker, true)
       markerClustererContext.requestRerender()
@@ -72,24 +74,29 @@ const advancedMarkerElement = useGoogleMapsResource<google.maps.marker.AdvancedM
   },
 })
 
-watch(() => props.options, (options) => {
-  if (advancedMarkerElement.value && options) {
-    Object.assign(advancedMarkerElement.value, options)
-  }
-}, { deep: true })
+watch(
+  () => [props.position?.lat, props.position?.lng, props.position, props.options],
+  () => {
+    if (!advancedMarkerElement.value)
+      return
 
-provide(ADVANCED_MARKER_ELEMENT_INJECTION_KEY, { advancedMarkerElement })
+    if (props.options)
+      Object.assign(advancedMarkerElement.value, props.options)
+    advancedMarkerElement.value.position = props.position ?? props.options?.position
+  },
+  { deep: true },
+)
 
-function setupEventListeners(marker: google.maps.marker.AdvancedMarkerElement) {
-  eventsWithoutPayload.forEach((event) => {
-    marker.addListener(event, () => emit(event))
-  })
-  eventsWithMapMouseEventPayload.forEach((event) => {
-    marker.addListener(event, (payload: google.maps.MapMouseEvent) => emit(event, payload))
-  })
-}
+provide(ADVANCED_MARKER_ELEMENT_INJECTION_KEY, { advancedMarkerElement })
 </script>
 
 <template>
+  <!-- Hidden container for #content slot — becomes the marker visual -->
+  <div v-if="$slots.content" style="display: none;">
+    <div ref="marker-content">
+      <slot name="content" />
+    </div>
+  </div>
+  <!-- Default slot for child components (InfoWindow, OverlayView, etc.) -->
   <slot v-if="advancedMarkerElement" />
 </template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue
index 163687d8..712c6fa6 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsCircle.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
 const props = defineProps<{
@@ -33,7 +34,10 @@ const eventsWithMapMouseEventPayload = [
 const circle = useGoogleMapsResource<google.maps.Circle>({
   create({ mapsApi, map }) {
     const c = new mapsApi.Circle({ map, ...props.options })
-    setupEventListeners(c)
+    bindGoogleMapsEvents(c, emit, {
+      noPayload: eventsWithoutPayload,
+      withPayload: eventsWithMapMouseEventPayload,
+    })
     return c
   },
   cleanup(c, { mapsApi }) {
@@ -47,15 +51,6 @@ watch(() => props.options, (options) => {
     circle.value.setOptions(options)
   }
 }, { deep: true })
-
-function setupEventListeners(c: google.maps.Circle) {
-  eventsWithoutPayload.forEach((event) => {
-    c.addListener(event, () => emit(event))
-  })
-  eventsWithMapMouseEventPayload.forEach((event) => {
-    c.addListener(event, (payload: google.maps.MapMouseEvent) => emit(event, payload))
-  })
-}
 </script>
 
 <template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsInfoWindow.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsInfoWindow.vue
index f7ae27cd..8ac01a23 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsInfoWindow.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsInfoWindow.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { inject, useTemplateRef, watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { ADVANCED_MARKER_ELEMENT_INJECTION_KEY, MARKER_INJECTION_KEY } from './injectionKeys'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
@@ -39,7 +40,7 @@ const infoWindow = useGoogleMapsResource<google.maps.InfoWindow>({
       ...props.options,
     })
 
-    setupEventListeners(iw)
+    bindGoogleMapsEvents(iw, emit, { noPayload: infoWindowEvents })
 
     if (markerContext?.marker.value) {
       markerClickListener = markerContext.marker.value.addListener('click', () => {
@@ -77,12 +78,6 @@ watch(() => props.options, (options) => {
     infoWindow.value.setOptions(options)
   }
 }, { deep: true })
-
-function setupEventListeners(iw: google.maps.InfoWindow) {
-  infoWindowEvents.forEach((event) => {
-    iw.addListener(event, () => emit(event))
-  })
-}
 </script>
 
 <template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue
index a7c41c80..80bd77b1 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsMarker.vue
@@ -1,5 +1,6 @@
 <script lang="ts">
 import { inject, provide, watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { MARKER_INJECTION_KEY } from './injectionKeys'
 import { MARKER_CLUSTERER_INJECTION_KEY } from './ScriptGoogleMapsMarkerClusterer.vue'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
@@ -9,6 +10,7 @@ export { MARKER_INJECTION_KEY } from './injectionKeys'
 
 <script setup lang="ts">
 const props = defineProps<{
+  position?: google.maps.LatLngLiteral | google.maps.LatLng
   options?: Omit<google.maps.MarkerOptions, 'map'>
 }>()
 
@@ -17,6 +19,10 @@ const emit = defineEmits<{
   (event: typeof eventsWithMapMouseEventPayload[number], payload: google.maps.MapMouseEvent): void
 }>()
 
+if (import.meta.dev) {
+  console.warn('[nuxt-scripts] ScriptGoogleMapsMarker uses the deprecated google.maps.Marker class. Use ScriptGoogleMapsAdvancedMarkerElement instead.')
+}
+
 const eventsWithoutPayload = [
   'animation_changed',
   'clickable_changed',
@@ -48,8 +54,14 @@ const markerClustererContext = inject(MARKER_CLUSTERER_INJECTION_KEY, undefined)
 
 const marker = useGoogleMapsResource<google.maps.Marker>({
   create({ mapsApi, map }) {
-    const m = new mapsApi.Marker(props.options)
-    setupEventListeners(m)
+    const m = new mapsApi.Marker({
+      ...props.options,
+      ...(props.position ? { position: props.position } : {}),
+    })
+    bindGoogleMapsEvents(m, emit, {
+      noPayload: eventsWithoutPayload,
+      withPayload: eventsWithMapMouseEventPayload,
+    })
     if (markerClustererContext?.markerClusterer.value) {
       markerClustererContext.markerClusterer.value.addMarker(m, true)
       markerClustererContext.requestRerender()
@@ -71,6 +83,12 @@ const marker = useGoogleMapsResource<google.maps.Marker>({
   },
 })
 
+watch(() => props.position, (position) => {
+  if (marker.value && position) {
+    marker.value.setPosition(position)
+  }
+})
+
 watch(() => props.options, (options) => {
   if (marker.value && options) {
     marker.value.setOptions(options)
@@ -78,15 +96,6 @@ watch(() => props.options, (options) => {
 }, { deep: true })
 
 provide(MARKER_INJECTION_KEY, { marker })
-
-function setupEventListeners(m: google.maps.Marker) {
-  eventsWithoutPayload.forEach((event) => {
-    m.addListener(event, () => emit(event))
-  })
-  eventsWithMapMouseEventPayload.forEach((event) => {
-    m.addListener(event, (payload: google.maps.MapMouseEvent) => emit(event, payload))
-  })
-}
 </script>
 
 <template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
new file mode 100644
index 00000000..a649209e
--- /dev/null
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
@@ -0,0 +1,216 @@
+<script setup lang="ts">
+import { inject, useTemplateRef, watch } from 'vue'
+import { ADVANCED_MARKER_ELEMENT_INJECTION_KEY, MARKER_INJECTION_KEY } from './injectionKeys'
+import { useGoogleMapsResource } from './useGoogleMapsResource'
+
+type OverlayAnchor = 'center' | 'top-left' | 'top-center' | 'top-right'
+  | 'bottom-left' | 'bottom-center' | 'bottom-right'
+  | 'left-center' | 'right-center'
+
+type OverlayPane = 'mapPane' | 'overlayLayer' | 'markerLayer'
+  | 'overlayMouseTarget' | 'floatPane'
+
+const props = withDefaults(defineProps<{
+  position?: google.maps.LatLngLiteral
+  anchor?: OverlayAnchor
+  offset?: { x: number, y: number }
+  pane?: OverlayPane
+  zIndex?: number
+  blockMapInteraction?: boolean
+}>(), {
+  anchor: 'bottom-center',
+  pane: 'floatPane',
+  blockMapInteraction: true,
+})
+
+const open = defineModel<boolean>('open')
+
+const markerContext = inject(MARKER_INJECTION_KEY, undefined)
+const advancedMarkerElementContext = inject(ADVANCED_MARKER_ELEMENT_INJECTION_KEY, undefined)
+
+// Read position fresh each call — NOT a computed, because Google Maps object
+// internal state (marker.getPosition()) is invisible to Vue's reactivity.
+// A computed would cache stale coordinates after marker drag.
+function getResolvedPosition(): google.maps.LatLngLiteral | undefined {
+  if (props.position)
+    return props.position
+  if (markerContext?.marker.value) {
+    const pos = markerContext.marker.value.getPosition()
+    if (pos)
+      return { lat: pos.lat(), lng: pos.lng() }
+  }
+  if (advancedMarkerElementContext?.advancedMarkerElement.value) {
+    const pos = advancedMarkerElementContext.advancedMarkerElement.value.position
+    if (pos) {
+      // position can be LatLng or LatLngLiteral
+      if ('lat' in pos && typeof pos.lat === 'function')
+        return { lat: (pos as google.maps.LatLng).lat(), lng: (pos as google.maps.LatLng).lng() }
+      return pos as google.maps.LatLngLiteral
+    }
+  }
+  return undefined
+}
+
+const ANCHOR_TRANSFORMS: Record<OverlayAnchor, string> = {
+  'center': 'translate(-50%, -50%)',
+  'top-left': 'translate(0, 0)',
+  'top-center': 'translate(-50%, 0)',
+  'top-right': 'translate(-100%, 0)',
+  'bottom-left': 'translate(0, -100%)',
+  'bottom-center': 'translate(-50%, -100%)',
+  'bottom-right': 'translate(-100%, -100%)',
+  'left-center': 'translate(0, -50%)',
+  'right-center': 'translate(-100%, -50%)',
+}
+
+const overlayContent = useTemplateRef('overlay-content')
+
+// Track all event listeners for clean teardown
+const listeners: google.maps.MapsEventListener[] = []
+
+const overlay = useGoogleMapsResource<google.maps.OverlayView>({
+  // ready condition accesses .value on ShallowRefs — tracked by whenever() in useGoogleMapsResource
+  ready: () => !!overlayContent.value
+    && !!(props.position || markerContext?.marker.value || advancedMarkerElementContext?.advancedMarkerElement.value),
+  create({ mapsApi, map }) {
+    const el = overlayContent.value!
+
+    class CustomOverlay extends mapsApi.OverlayView {
+      override onAdd() {
+        const panes = this.getPanes()
+        if (panes) {
+          panes[props.pane].appendChild(el)
+          if (props.blockMapInteraction)
+            mapsApi.OverlayView.preventMapHitsAndGesturesFrom(el)
+        }
+      }
+
+      override draw() {
+        // v-model:open support: hide when explicitly closed
+        if (open.value === false) {
+          el.style.visibility = 'hidden'
+          return
+        }
+
+        const position = getResolvedPosition()
+        if (!position) {
+          el.style.visibility = 'hidden'
+          return
+        }
+        const projection = this.getProjection()
+        if (!projection) {
+          el.style.visibility = 'hidden'
+          return
+        }
+        const pos = projection.fromLatLngToDivPixel(
+          new mapsApi.LatLng(position.lat, position.lng),
+        )
+        if (!pos) {
+          el.style.visibility = 'hidden'
+          return
+        }
+        el.style.position = 'absolute'
+        el.style.left = `${pos.x + (props.offset?.x ?? 0)}px`
+        el.style.top = `${pos.y + (props.offset?.y ?? 0)}px`
+        el.style.transform = ANCHOR_TRANSFORMS[props.anchor]
+        if (props.zIndex !== undefined)
+          el.style.zIndex = String(props.zIndex)
+        el.style.visibility = 'visible'
+      }
+
+      override onRemove() {
+        el.parentNode?.removeChild(el)
+      }
+    }
+
+    // Prevent flash: hide until first draw() positions content
+    el.style.visibility = 'hidden'
+
+    const ov = new CustomOverlay()
+    ov.setMap(map)
+
+    // Follow parent marker position changes
+    if (markerContext?.marker.value) {
+      // Legacy Marker fires position_changed on drag and programmatic moves
+      listeners.push(
+        markerContext.marker.value.addListener('position_changed', () => ov.draw()),
+      )
+    }
+    else if (advancedMarkerElementContext?.advancedMarkerElement.value) {
+      const ame = advancedMarkerElementContext.advancedMarkerElement.value
+      // AdvancedMarkerElement fires drag continuously during drag
+      listeners.push(
+        ame.addListener('drag', () => ov.draw()),
+        ame.addListener('dragend', () => ov.draw()),
+      )
+    }
+
+    return ov
+  },
+  cleanup(ov) {
+    listeners.forEach(l => l.remove())
+    listeners.length = 0
+    ov.setMap(null)
+  },
+})
+
+// AdvancedMarkerElement doesn't fire position_changed, so watch the reactive ref
+// for programmatic position updates (drag is handled by event listeners above)
+if (advancedMarkerElementContext) {
+  watch(
+    () => {
+      const pos = advancedMarkerElementContext.advancedMarkerElement.value?.position
+      if (!pos)
+        return undefined
+      if ('lat' in pos && typeof pos.lat === 'function')
+        return { lat: (pos as google.maps.LatLng).lat(), lng: (pos as google.maps.LatLng).lng() }
+      return pos as google.maps.LatLngLiteral
+    },
+    () => { overlay.value?.draw() },
+  )
+}
+
+// Reposition on prop changes (draw() is designed to be called repeatedly)
+// Only watches explicit props — marker position changes are handled by event listeners above
+watch(
+  () => [props.position?.lat, props.position?.lng, props.offset?.x, props.offset?.y, props.zIndex, props.anchor],
+  () => { overlay.value?.draw() },
+)
+
+// v-model:open — toggle visibility without remounting the overlay
+watch(() => open.value, () => {
+  if (!overlay.value)
+    return
+  overlay.value.draw()
+})
+
+// Pane change requires remount (setMap cycles onRemove + onAdd + draw)
+watch(() => props.pane, () => {
+  if (overlay.value) {
+    const map = overlay.value.getMap()
+    overlay.value.setMap(null)
+    if (map)
+      overlay.value.setMap(map as google.maps.Map)
+  }
+})
+
+// blockMapInteraction change requires remount to re-apply preventMapHitsAndGesturesFrom
+watch(() => props.blockMapInteraction, () => {
+  if (overlay.value) {
+    const map = overlay.value.getMap()
+    overlay.value.setMap(null)
+    if (map)
+      overlay.value.setMap(map as google.maps.Map)
+  }
+})
+
+defineExpose({ overlay })
+</script>
+
+<template>
+  <div style="display: none;">
+    <div ref="overlay-content">
+      <slot />
+    </div>
+  </div>
+</template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolygon.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolygon.vue
index 99a79bc9..204ca5a3 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolygon.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolygon.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
 const props = defineProps<{
@@ -31,7 +32,9 @@ const eventsWithMapMouseEventPayload = [
 const polygon = useGoogleMapsResource<google.maps.Polygon>({
   create({ mapsApi, map }) {
     const p = new mapsApi.Polygon({ map, ...props.options })
-    setupEventListeners(p)
+    bindGoogleMapsEvents(p, emit, {
+      withPayload: [...eventsWithPolyMouseEventPayload, ...eventsWithMapMouseEventPayload],
+    })
     return p
   },
   cleanup(p, { mapsApi }) {
@@ -45,15 +48,6 @@ watch(() => props.options, (options) => {
     polygon.value.setOptions(options)
   }
 }, { deep: true })
-
-function setupEventListeners(p: google.maps.Polygon) {
-  eventsWithPolyMouseEventPayload.forEach((event) => {
-    p.addListener(event, (payload: google.maps.PolyMouseEvent) => emit(event, payload))
-  })
-  eventsWithMapMouseEventPayload.forEach((event) => {
-    p.addListener(event, (payload: google.maps.MapMouseEvent) => emit(event, payload))
-  })
-}
 </script>
 
 <template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolyline.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolyline.vue
index 8a8e1b62..6d07e694 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolyline.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsPolyline.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
 const props = defineProps<{
@@ -31,7 +32,9 @@ const eventsWithMapMouseEventPayload = [
 const polyline = useGoogleMapsResource<google.maps.Polyline>({
   create({ mapsApi, map }) {
     const p = new mapsApi.Polyline({ map, ...props.options })
-    setupEventListeners(p)
+    bindGoogleMapsEvents(p, emit, {
+      withPayload: [...eventsWithPolyMouseEventPayload, ...eventsWithMapMouseEventPayload],
+    })
     return p
   },
   cleanup(p, { mapsApi }) {
@@ -45,15 +48,6 @@ watch(() => props.options, (options) => {
     polyline.value.setOptions(options)
   }
 }, { deep: true })
-
-function setupEventListeners(p: google.maps.Polyline) {
-  eventsWithPolyMouseEventPayload.forEach((event) => {
-    p.addListener(event, (payload: google.maps.PolyMouseEvent) => emit(event, payload))
-  })
-  eventsWithMapMouseEventPayload.forEach((event) => {
-    p.addListener(event, (payload: google.maps.MapMouseEvent) => emit(event, payload))
-  })
-}
 </script>
 
 <template>
diff --git a/src/runtime/components/GoogleMaps/ScriptGoogleMapsRectangle.vue b/src/runtime/components/GoogleMaps/ScriptGoogleMapsRectangle.vue
index 42b56331..ab552a64 100644
--- a/src/runtime/components/GoogleMaps/ScriptGoogleMapsRectangle.vue
+++ b/src/runtime/components/GoogleMaps/ScriptGoogleMapsRectangle.vue
@@ -1,5 +1,6 @@
 <script setup lang="ts">
 import { watch } from 'vue'
+import { bindGoogleMapsEvents } from './bindGoogleMapsEvents'
 import { useGoogleMapsResource } from './useGoogleMapsResource'
 
 const props = defineProps<{
@@ -32,7 +33,10 @@ const eventsWithMapMouseEventPayload = [
 const rectangle = useGoogleMapsResource<google.maps.Rectangle>({
   create({ mapsApi, map }) {
     const r = new mapsApi.Rectangle({ map, ...props.options })
-    setupEventListeners(r)
+    bindGoogleMapsEvents(r, emit, {
+      noPayload: eventsWithoutPayload,
+      withPayload: eventsWithMapMouseEventPayload,
+    })
     return r
   },
   cleanup(r, { mapsApi }) {
@@ -46,15 +50,6 @@ watch(() => props.options, (options) => {
     rectangle.value.setOptions(options)
   }
 }, { deep: true })
-
-function setupEventListeners(r: google.maps.Rectangle) {
-  eventsWithoutPayload.forEach((event) => {
-    r.addListener(event, () => emit(event))
-  })
-  eventsWithMapMouseEventPayload.forEach((event) => {
-    r.addListener(event, (payload: google.maps.MapMouseEvent) => emit(event, payload))
-  })
-}
 </script>
 
 <template>
diff --git a/src/runtime/components/GoogleMaps/bindGoogleMapsEvents.ts b/src/runtime/components/GoogleMaps/bindGoogleMapsEvents.ts
new file mode 100644
index 00000000..93b555f8
--- /dev/null
+++ b/src/runtime/components/GoogleMaps/bindGoogleMapsEvents.ts
@@ -0,0 +1,22 @@
+/**
+ * Bind Google Maps event listeners that forward to Vue emit.
+ *
+ * Two categories:
+ * - `noPayload`: emits with no arguments (state-change events like `position_changed`)
+ * - `withPayload`: forwards the first argument from the listener (mouse events, etc.)
+ */
+export function bindGoogleMapsEvents(
+  instance: { addListener: (event: string, handler: (...args: any[]) => void) => void },
+  emit: (...args: any[]) => void,
+  config: {
+    noPayload?: readonly string[]
+    withPayload?: readonly string[]
+  },
+) {
+  config.noPayload?.forEach((event) => {
+    instance.addListener(event, () => emit(event))
+  })
+  config.withPayload?.forEach((event) => {
+    instance.addListener(event, (payload: any) => emit(event, payload))
+  })
+}