Api

<ScriptGoogleMaps>

Copy for LLMs

The <ScriptGoogleMaps> component is a wrapper around the useScriptGoogleMaps() composable. It provides a simple way to embed Google Maps in your Nuxt app.

triggerElementScriptTrigger

Defines the trigger event to load the script.

apiKeystring

Defines the Google Maps API key. Must have access to the Static Maps API as well.

centergoogle.maps.LatLng | google.maps.LatLngLiteral | `${string},${string}`

A latitude / longitude of where to focus the map.

zoomnumber

Zoom level for the map (0-21). Reactive: changing this will update the map. Takes precedence over mapOptions.zoom when provided.

mapOptionsgoogle.maps.MapOptions

Options for the map.

regionstring

Defines the region of the map.

languagestring

Defines the language of the map

versionstring

Defines the version of google maps js API

widthnumber | string

Defines the width of the map.

heightnumber | string

Defines the height of the map

rootAttrsHTMLAttributes & ReservedProps & Record<string, unknown>

Customize the root element attributes.

mapIds{ light?: string, dark?: string }

Map IDs for light and dark color modes. When provided, the map will automatically switch styles based on color mode. Requires @nuxtjs/color-mode or manual colorMode prop.

colorMode'light' | 'dark'

Manual color mode control. When provided, overrides auto-detection from @nuxtjs/color-mode. Accepts 'light', 'dark', or a reactive ref.

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

Template Ref API

Access the basic Google Maps instances via a template ref. The exposed object contains:

PropertyTypeDescription
googleMapsRef<typeof google.maps | undefined>The core Maps API library.
mapShallowRef<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>
Edit this page
Markdown For LLMs

Billing & Permissions

<ScriptGoogleMapsHeatmapLayer>

Heatmap visualization layer. Place inside a <ScriptGoogleMaps> component. The component automatically loads the visualization library.