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.

<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.

<template>
  <ScriptGoogleMaps
    trigger="immediate"
    :center="{ lat: -33.8688, lng: 151.2093 }"
    :zoom="12"
  />
</template>

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

Replace the default Google Static Maps image with your own to avoid Static Maps API charges. See the #placeholder slot for usage.

Marker Performance

When rendering many markers, use marker clustering to group nearby markers. This significantly reduces DOM elements and improves pan/zoom performance.

See Billing & Permissions for a full cost breakdown and optimization strategies.