Skip to main content
Api

<ScriptGoogleMaps>

Copy for LLMs

<ScriptGoogleMaps> wraps useScriptGoogleMaps() with lazy loading and a declarative component API.

triggerElementScriptTrigger = ['mouseenter', 'mouseover', 'mousedown']

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.

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 = 640

Defines the width of the map.

heightnumber | string = 400

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' or 'dark'.

An Element Event Trigger delays Google Maps until a configured event occurs on the component.

The #placeholder slot is empty by default. Use <ScriptGoogleMapsStaticMap> inside it to show a static map image while the interactive map loads.

The default events are mouseenter, mouseover, and mousedown.

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
mapsApitypeof google.maps | undefinedThe core Maps API namespace (google.maps).
mapgoogle.maps.Map | undefinedThe map instance.
resolveQueryToLatLng(query) => Promise<google.maps.LatLng | google.maps.LatLngLiteral | undefined>Geocode an address to coordinates. The promise rejects when Google returns no location or the request fails.
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>

Vue unwraps the exposed refs when you access them through a component template ref, as in the example above. The @ready payload uses the raw exposed object, so its mapsApi and map properties are ShallowRefs.

Map events

Use the component's @ready event to attach Google Maps listeners after initialization. The callback receives the raw exposed object.

<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

Use the slots to add content before, during, and after the map loads.

default

The default slot renders inside the map root. Changing the map ID or color scheme briefly unmounts and remounts it with the map's other declarative children.

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

The default is an accessible loading indicator. Supplying the slot replaces it, so include an equivalent loading announcement in custom content.

The current component also renders the loading slot when the script status is error. If you provide both loading and error, both can appear after a load failure.
<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
    :map-options="{
      center,
      zoom: 7,
    }"
  >
    <template #placeholder>
      <ScriptGoogleMapsStaticMap
        :center="center"
        :zoom="7"
        loading="eager"
      />
    </template>
  </ScriptGoogleMaps>
</template>
Was this page helpful?
Edit this page
Markdown For LLMs

Billing & Permissions

Enable the Google Maps APIs you use and estimate their effect on billing.

<ScriptGoogleMapsOverlayView>

Position custom Vue content over a Google map or marker.