Api

useScriptGoogleMaps()

Copy for LLMs

The useScriptGoogleMaps() composable lets you have fine-grained control over the Google Maps SDK. It provides a way to load the Google Maps SDK and interact with it programmatically.

export function useScriptGoogleMaps<T extends GoogleMapsApi>(_options?: GoogleMapsInput) {}

Please follow the Registry Scripts guide to learn more about advanced usage.

Options

OptionTypeDefaultDescription
apiKeystring-Your Google Maps API key (required).
librariesstring[]['places']Google Maps libraries to load.
languagestring-Language for controls and labels (e.g., 'en', 'ja').
regionstring-Region biasing (e.g., 'US', 'JP').
vstring-API version: 'weekly', 'quarterly', 'beta', or 'alpha'. Omitted by default (Google defaults to 'weekly').

Return Values

PropertyTypeDescription
onLoaded(fn) => voidCallback when the SDK is ready. Receives the Google Maps API instance.
load() => PromiseManually trigger script loading.
statusRef<string>Current loading status ('awaitingLoad', 'loading', 'loaded', 'error').

Examples

Basic Map

Loading the Google Maps SDK and creating a map programmatically.

<script setup lang="ts">
/// <reference types="google.maps" />
const { onLoaded } = useScriptGoogleMaps({
  apiKey: 'key',
})
const mapEl = ref()
onMounted(() => {
  onLoaded(async (instance) => {
    const maps = await instance.maps
    new maps.Map(mapEl.value, {
      center: { lat: -34.397, lng: 150.644 },
      zoom: 8,
    })
  })
})
</script>

<template>
  <div ref="mapEl" style="width: 100%; height: 400px;" />
</template>

Geocoding

Use the composable to access the Geocoder API.

<script setup lang="ts">
const { onLoaded } = useScriptGoogleMaps({
  apiKey: 'key',
  libraries: ['geocoding'],
})

async function geocodeAddress(address: string) {
  onLoaded(async (instance) => {
    const maps = await instance.maps
    const geocoder = new maps.Geocoder()
    const result = await geocoder.geocode({ address })
    console.log(result.results[0]?.geometry.location.toJSON())
  })
}
</script>

Import Additional Libraries

Load additional libraries at runtime (e.g., Places, Drawing).

<script setup lang="ts">
const { onLoaded } = useScriptGoogleMaps({
  apiKey: 'key',
})

onMounted(() => {
  onLoaded(async (instance) => {
    const maps = await instance.maps
    const places = await maps.importLibrary('places')
    // Use places API
  })
})
</script>
Prefer the <ScriptGoogleMaps> component for most use cases. It handles lazy loading, placeholder images, and provides a declarative API. Use useScriptGoogleMaps() when you need direct SDK access or are building custom integrations.
Edit this page
Markdown For LLMs

<ScriptGoogleMapsOverlayView>

Renders arbitrary Vue slot content at a map lat/lng position. Unlike InfoWindow, you have full control over HTML structure and styling.

<ScriptGoogleMapsStaticMap>

Renders a Google Maps Static API image. Use standalone for static map previews, or drop into the #placeholder slot of <ScriptGoogleMaps> for a loading placeholder.