<ScriptGoogleMaps>
The <ScriptGoogleMaps> component is a wrapper around the useScriptGoogleMaps() composable. It provides a simple way to embed Google Maps in your Nuxt app.
interface ScriptGoogleMapsProps ScriptGoogleMapsPropsIt's optimized for performance by using the Element Event Triggers, only loading the Google Maps when specific elements events happen.
The #placeholder slot is empty by default. Use <ScriptGoogleMapsStaticMap> inside it to show a static map image while the interactive map loads.
By default, it will load on the mouseenter, mouseover, and mousedown events.
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 | ShallowRef<typeof google.maps | undefined> | The core Maps API namespace (google.maps). |
googleMaps | ShallowRef<typeof google.maps | undefined> | Deprecated. Alias for mapsApi; emits a dev-mode warning. Slated for removal in a future major version. |
map | ShallowRef<google.maps.Map> | The map instance. |
resolveQueryToLatLng | (query) => Promise<LatLngLiteral> | Geocode an address to coordinates. |
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>
Map Events
Subscribe to Google Maps events using the @ready event. The callback receives the same object as the template ref.
<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.
<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).
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.
<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 :center="center" :zoom="7">
<template #placeholder>
<ScriptGoogleMapsStaticMap
:center="center"
:zoom="7"
loading="eager"
/>
</template>
</ScriptGoogleMaps>
</template>