diff --git a/docs/content/scripts/google-maps/2.api/11.overlay-view.md b/docs/content/scripts/google-maps/2.api/11.overlay-view.md
index b501faa1..460e3ca9 100644
--- a/docs/content/scripts/google-maps/2.api/11.overlay-view.md
+++ b/docs/content/scripts/google-maps/2.api/11.overlay-view.md
@@ -31,6 +31,45 @@ When nested inside a `ScriptGoogleMapsMarker`, the overlay automatically inherit
```
+## Controlled vs Uncontrolled Open State
+
+The overlay supports two open-state patterns: uncontrolled (component-managed) and controlled (parent-managed via `v-model:open`).
+
+**Uncontrolled.** The component owns its open state. The overlay opens by default; pass `:default-open="false"` to start closed. This is the simplest pattern when you don't need to react to state changes from the parent.
+
+```vue
+
+
+
+ Always-open label
+
+
+
+
+ Initially hidden
+
+
+```
+
+**Controlled.** Bind `v-model:open` to a parent ref. The parent owns the state and the overlay reflects it. The overlay updates the bound ref when something internal flips it (for example, the marker-cluster auto-hide behaviour).
+
+```vue
+
+
+
+
+ Controlled by parent
+
+
+```
+
+When `v-model:open` is bound, `defaultOpen` has no effect; pass an initial value to the bound ref instead.
+
## Popup on Marker Click
Using `v-model:open` keeps the overlay mounted, toggling visibility via CSS. This avoids remount cost and preserves internal state.
@@ -94,6 +133,33 @@ For simple cases where remounting is acceptable, `v-if` also works:
```
+## Position Format
+
+The `position` prop accepts either a plain `LatLngLiteral` (`{ lat, lng }`) or a `google.maps.LatLng` instance, so you can pass values straight from the Maps API without converting them first.
+
+```vue
+
+
+
+
+
+ Resolved position
+
+
+
+```
+
## Map Panning
When an overlay opens, the map automatically pans so the overlay is fully visible, matching the native `InfoWindow` behavior. The default padding is 40px from the map edge.
diff --git a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
index 160dbced..e1e79147 100644
--- a/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
+++ b/packages/script/src/runtime/components/GoogleMaps/ScriptGoogleMapsOverlayView.vue
@@ -11,9 +11,21 @@ export type ScriptGoogleMapsOverlayPane = 'mapPane' | 'overlayLayer' | 'markerLa
export interface ScriptGoogleMapsOverlayViewProps {
/**
* Geographic position for the overlay. Falls back to parent marker position if omitted.
+ *
+ * Accepts either a plain `LatLngLiteral` (`{ lat, lng }`) or a
+ * `google.maps.LatLng` instance.
* @see https://developers.google.com/maps/documentation/javascript/reference/overlay-view#OverlayView
*/
- position?: google.maps.LatLngLiteral
+ position?: google.maps.LatLng | google.maps.LatLngLiteral
+ /**
+ * Initial open state for the uncontrolled mode (when `v-model:open` is not
+ * bound). When omitted, the overlay opens on mount, matching v0 behaviour.
+ *
+ * Has no effect when `v-model:open` is used; pass an initial value to the
+ * bound ref instead.
+ * @default true
+ */
+ defaultOpen?: boolean
/**
* Anchor point of the overlay relative to its position.
* @default 'bottom-center'
@@ -80,43 +92,58 @@ export interface ScriptGoogleMapsOverlayViewExpose {