Guides

Performance

Copy for LLMs

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>
Immediate loading charges the Maps JavaScript API ($7/1000) on every page view. Only use this when the map is essential to the page experience.

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, mark it for priority loading. This sets the placeholder image to loading="eager" and adds a preconnect hint.

<template>
  <ScriptGoogleMaps above-the-fold />
</template>

Custom Placeholder

Replace the default Google Static Maps image with your own custom image to avoid Static Maps API charges. Useful when you have a screenshot or illustration of the map area.

<template>
  <ScriptGoogleMaps>
    <template #placeholder>
      <img src="/map-preview.webp" alt="Map of Sydney" style="width: 100%; height: 100%; object-fit: cover;">
    </template>
  </ScriptGoogleMaps>
</template>

You can also access the generated static map URL if you want to use it with custom styling. Note that rendering the placeholder URL still makes a Static Maps API request and incurs charges:

<template>
  <ScriptGoogleMaps>
    <template #placeholder="{ placeholder }">
      <img :src="placeholder" alt="Map" style="filter: grayscale(1);">
    </template>
  </ScriptGoogleMaps>
</template>

Loading State

Show a custom indicator while the JavaScript API loads:

<template>
  <ScriptGoogleMaps>
    <template #loading>
      <div style="display: flex; align-items: center; justify-content: center; height: 100%;">
        Loading map...
      </div>
    </template>
  </ScriptGoogleMaps>
</template>

Marker Performance

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

<template>
  <ScriptGoogleMaps :center="center" :zoom="10">
    <ScriptGoogleMapsMarkerClusterer>
      <ScriptGoogleMapsAdvancedMarkerElement
        v-for="place in places"
        :key="place.id"
        :position="place.position"
      />
    </ScriptGoogleMapsMarkerClusterer>
  </ScriptGoogleMaps>
</template>

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

Edit this page
Markdown For LLMs

Google Maps

Show performance-optimized Google Maps in your Nuxt app.

Programmatic API

The ScriptGoogleMaps component exposes its internal APIs via template ref, giving you full control beyond what the declarative SFC components provide.