<ScriptGoogleMaps>
<ScriptGoogleMaps> wraps useScriptGoogleMaps() with lazy loading and a declarative component API.
interface ScriptGoogleMapsProps ScriptGoogleMapsPropsAn Element Event Trigger delays Google Maps until a configured event occurs on the component.
The #placeholder slot is empty by default. Use <ScriptGoogleMapsStaticMap> inside it to show a static map image while the interactive map loads.
The default events are mouseenter, mouseover, and mousedown.
See the Facade Component API for all props, events, and slots.
center and zoom props are now deprecated. Pass them via mapOptions instead. The legacy props still work and emit a dev-mode warning when used. mapOptions.center and mapOptions.zoom take precedence when both are set.<template>
<!-- Before (deprecated) -->
<ScriptGoogleMaps :center="{ lat, lng }" :zoom="12" />
<!-- After -->
<ScriptGoogleMaps :map-options="{ center: { lat, lng }, zoom: 12 }" />
</template>
Template Ref API
Access the basic Google Maps instances via a template ref. The exposed object contains:
| Property | Type | Description |
|---|---|---|
mapsApi | typeof google.maps | undefined | The core Maps API namespace (google.maps). |
googleMaps | typeof google.maps | undefined | Deprecated. Alias for mapsApi; emits a dev-mode warning. Slated for removal in a future major version. |
map | google.maps.Map | undefined | The map instance. |
resolveQueryToLatLng | (query) => Promise<google.maps.LatLng | google.maps.LatLngLiteral | undefined> | Geocode an address to coordinates. The promise rejects when Google returns no location or the request fails. |
importLibrary | (name) => Promise<Library> | Load additional Google Maps libraries at runtime. |
<script setup lang="ts">
const mapRef = ref()
async function flyToSydney() {
const coords = await mapRef.value?.resolveQueryToLatLng('Sydney, Australia')
if (coords)
mapRef.value?.map?.panTo(coords)
}
</script>
<template>
<ScriptGoogleMaps ref="mapRef" api-key="your-api-key" />
<button @click="flyToSydney">
Go to Sydney
</button>
</template>
Vue unwraps the exposed refs when you access them through a component template ref, as in the example above. The @ready payload uses the raw exposed object, so its mapsApi, googleMaps, and map properties are ShallowRefs.
Map events
Use the component's @ready event to attach Google Maps listeners after initialization. The callback receives the raw exposed object.
<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
Use the slots to add content before, during, and after the map loads.
default
The default slot renders inside the map root. Changing the map ID or color scheme briefly unmounts and remounts it with the map's other declarative children.
<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.
<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).
The default is an accessible loading indicator. Supplying the slot replaces it, so include an equivalent loading announcement in custom content.
loading slot when the script status is error. If you provide both loading and error, both can appear after a load failure.<template>
<ScriptGoogleMaps>
<template #loading>
<div class="bg-blue-500 text-white p-5">
Loading...
</div>
</template>
</ScriptGoogleMaps>
</template>
placeholder
The placeholder slot is empty by default. Use <ScriptGoogleMapsStaticMap> to show a static map preview while the interactive map loads.
<template>
<ScriptGoogleMaps
:map-options="{
center,
zoom: 7,
}"
>
<template #placeholder>
<ScriptGoogleMapsStaticMap
:center="center"
:zoom="7"
loading="eager"
/>
</template>
</ScriptGoogleMaps>
</template>