Performance
ScriptGoogleMaps waits for an interaction before requesting the Maps JavaScript API. The placeholder slot stays empty unless you add a static map or another preview. Google also recommends the API's asynchronous loading path, which the Nuxt Scripts registry uses through loading=async and a callback. See Google's loading guide.
Loading Strategies
Default: lazy
By default, the map loads on mouseenter, mouseover, or mousedown. A page view that never triggers the map does not load the Maps JavaScript API.
<template>
<!-- Loads JS API on first hover/click -->
<ScriptGoogleMaps
:map-options="{
center: { lat: -33.8688, lng: 151.2093 },
zoom: 12,
}"
/>
</template>
Immediate loading
Skips the interaction gate, but still waits for client hydration and Nuxt's idle callback before loading the JavaScript API. Use this when the map is primary content and should become interactive soon after hydration.
<template>
<ScriptGoogleMaps
trigger="immediate"
:map-options="{
center: { lat: -33.8688, lng: 151.2093 },
zoom: 12,
}"
/>
</template>
A map load triggers the Dynamic Maps SKU, regardless of which trigger starts it. With trigger="immediate", every visit that renders the component can become a map load. See Billing & Permissions for current prices.
Custom triggers
You can control exactly when the map loads using any Element Event Trigger.
<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, use the #placeholder slot to provide an eagerly loaded custom image and avoid Static Maps API charges.
Custom Placeholder
The slot is empty by default. Add your own preview without creating a Static Maps API event; see the #placeholder slot for usage.
Marker performance
When rendering many markers, consider marker clustering. At lower zoom levels, the clusterer replaces groups of nearby markers with one cluster marker; Google describes this as a way to improve readability when markers are close together in its marker clustering guide.
See Billing & Permissions for a full cost breakdown and optimization strategies.