Skip to main content
Scripts

Google Maps

Copy for LLMs

Google Maps provides interactive and static maps for websites.

Nuxt Scripts provides a useScriptGoogleMaps() composable and a headless <ScriptGoogleMaps> component for working with Google Maps.

apiKeystring required

Your Google Maps API key.

librariesstring[] = ['places']

The Google Maps libraries to load.

languagestring

The language code for the map UI and geocoding results.

regionstring

The region code to bias geocoding results.

v'weekly' | 'quarterly' | 'beta' | 'alpha' | string = 'weekly'

The Google Maps JS API version to load.

Types

Install @types/google.maps for full TypeScript support.

pnpm add -D @types/google.maps

Setup

Enable Google Maps in your nuxt.config and provide your API key via environment variable:

nuxt.config.ts
export default defineNuxtConfig({
  scripts: {
    registry: {
      // Register infrastructure without loading Maps on every page.
      // <ScriptGoogleMaps> will load it after its element trigger fires.
      googleMaps: {},
    },
  },
})
.env
NUXT_PUBLIC_SCRIPTS_GOOGLE_MAPS_API_KEY=<YOUR_API_KEY>

Registering Google Maps also adds server proxy routes that keep the key out of static-map and geocoding request URLs:

  • /_scripts/proxy/google-static-maps for placeholder images
  • /_scripts/proxy/google-maps-geocode for location search

Add trigger: 'onNuxtReady' to the registry entry only when you want the interactive Maps API to load globally. It bypasses the component's default interaction delay because the shared script instance is already loading.

The Maps JavaScript API still sends the key to the browser when the interactive map loads. Follow Google's API security guidance: restrict keys by application and API, and use separate keys for client-side and server-side services when possible. Passing api-key directly on <ScriptGoogleMaps> also exposes it in the client bundle, whereas runtime config lets you vary the key by deployment.

Google's Maps Platform FAQ requires browser pages to load Static Maps images directly from Google. The current static-map proxy caches and serves those images, so pass an explicit api-key to <ScriptGoogleMapsStaticMap> to bypass the proxy and review the Maps Platform terms before using that component.

This script's proxy endpoints use HMAC URL signing when you configure a NUXT_SCRIPTS_PROXY_SECRET. See the security guide for setup instructions.

See Billing & Permissions for API costs and required permissions.

Quick Start

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

See the Markers & Info Windows guide for adding markers, popups, and custom content. See Shapes & Overlays for drawing on the map.

Edit this page
Markdown For LLMs

Google Analytics

Send Google Analytics page views and events with typed consent controls.

Performance

Defer the Maps JavaScript API, reserve map space, and reduce unnecessary dynamic map loads.