---
title: "<ScriptGoogleMaps> · Nuxt Scripts"
description: "Lazy-load an interactive Google map and compose it with declarative child components."
canonical_url: "https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps"
meta:
  "og:description": "Lazy-load an interactive Google map and compose it with declarative child components."
  "og:image": "https://scripts.nuxt.com/_og/s/o_c8c1c92f7ef86a5a.png"
  "og:image:height": "600"
  "og:image:type": image/png
  "og:image:width": "1200"
  "og:title": "<ScriptGoogleMaps> · Nuxt Scripts"
  "twitter:image": "https://scripts.nuxt.com/_og/s/o_c8c1c92f7ef86a5a.png"
---

> Index of every page on this site: [llms.txt](https://scripts.nuxt.com/llms.txt)

**Api**

# **\<ScriptGoogleMaps>**

[Copy for LLMs](https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps.md)

[`**<ScriptGoogleMaps>**`](https://scripts.nuxt.com/scripts/google-maps) wraps [`**useScriptGoogleMaps()**`](https://scripts.nuxt.com/scripts/google-maps/api/use-script-google-maps) with lazy loading and a declarative component API.

`**trigger**``ElementScriptTrigger` = \['mouseenter', 'mouseover', 'mousedown']

Defines the trigger event to load the script.

`**apiKey**``string`

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

`**mapOptions**``google.maps.MapOptions`

Options for the map.

`**region**``string`

Defines the region of the map.

`**language**``string`

Defines the language of the map.

`**version**``string`

Defines the version of google maps js API.

`**width**``number | string` = 640

Defines the width of the map.

`**height**``number | string` = 400

Defines the height of the map.

`**rootAttrs**``HTMLAttributes & 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**](https://scripts.nuxt.com/docs/guides/script-triggers#element-event-triggers) delays Google Maps until a configured event occurs on the component.

The `**#placeholder**` slot is empty by default. Use [`**<ScriptGoogleMapsStaticMap>**`](https://scripts.nuxt.com/scripts/google-maps/api/static-map) 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**](https://scripts.nuxt.com/docs/guides/facade-components#facade-components-api) for all props, events, and slots.

## Template Ref API

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

| **Property** | **Type** | **Description** |
| --- | --- | --- |
| `**mapsApi**` | `**typeof google.maps \| undefined**` | The core Maps API namespace (`**google.maps**`). |
| `**map**` | `**google.maps.Map \| undefined**` | The 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. |

```vue
<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 `**ShallowRef**`s.

## Map events

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

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

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

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

```vue
<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>**`](https://scripts.nuxt.com/scripts/google-maps/api/static-map) to show a static map preview while the interactive map loads.

```vue
<template>
  <ScriptGoogleMaps
    :map-options="{
      center,
      zoom: 7,
    }"
  >
    <template #placeholder>
      <ScriptGoogleMapsStaticMap
        :center="center"
        :zoom="7"
        loading="eager"
      />
    </template>
  </ScriptGoogleMaps>
</template>
```

[Edit this page](https://github.com/nuxt/scripts/edit/main/docs/content/google-maps/2.api/1.script-google-maps.md)

[Markdown For LLMs](https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps.md)

[**Billing & Permissions** Enable the Google Maps APIs you use and estimate their effect on billing.](https://scripts.nuxt.com/scripts/google-maps/guides/billing) [**\<ScriptGoogleMapsOverlayView>** Position custom Vue content over a Google map or marker.](https://scripts.nuxt.com/scripts/google-maps/api/overlay-view)

**On this page **

- [Template Ref API](#template-ref-api)
- [Map events](#map-events)
- [Slots](#slots)

```json
{"@context":"https://schema.org","@graph":[{"@id":"https://scripts.nuxt.com/#website","@type":"WebSite","description":"Nuxt Scripts lets you load third-party scripts with better performance, privacy, security and DX. It includes many popular third-parties out of the box.","name":"Nuxt Scripts","url":"https://scripts.nuxt.com/","publisher":{"@id":"https://scripts.nuxt.com/#identity"}},{"@id":"https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps#webpage","@type":"WebPage","description":"Lazy-load an interactive Google map and compose it with declarative child components.","name":"<ScriptGoogleMaps>","url":"https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps","breadcrumb":{"@id":"https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps#breadcrumb"},"isPartOf":{"@id":"https://scripts.nuxt.com/#website"},"potentialAction":[{"@type":"ReadAction","target":["https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps"]}],"primaryImageOfPage":{"@id":"https://scripts.nuxt.com/#logo"}},{"@id":"https://scripts.nuxt.com/#identity","@type":"Organization","name":"Nuxt Scripts","url":"https://scripts.nuxt.com","logo":{"@id":"https://scripts.nuxt.com/#logo"}},{"@id":"https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps#breadcrumb","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","name":"Nuxt Scripts","item":"https://scripts.nuxt.com/","position":1},{"@type":"ListItem","name":"Scripts","item":"https://scripts.nuxt.com/scripts","position":2},{"@type":"ListItem","name":"Google Maps","item":"https://scripts.nuxt.com/scripts/google-maps","position":3},{"@type":"ListItem","name":"API","item":"https://scripts.nuxt.com/scripts/google-maps/api","position":4},{"@type":"ListItem","name":"<ScriptGoogleMaps>","item":"https://scripts.nuxt.com/scripts/google-maps/api/script-google-maps","position":5}]},{"@id":"https://scripts.nuxt.com/#logo","@type":"ImageObject","caption":"Nuxt Scripts","contentUrl":"https://scripts.nuxt.com/logo.svg","inLanguage":"en","url":"https://scripts.nuxt.com/logo.svg"}]}
```

## Sitemap

See the full [sitemap](https://scripts.nuxt.com/sitemap.md) for all pages.
