Api
useScriptGoogleMaps()
Use useScriptGoogleMaps() to load the SDK and work with the Maps API directly.
export function useScriptGoogleMaps<T extends GoogleMapsApi>(_options?: GoogleMapsInput) {}
For triggers and other script options, see Registry Scripts.
Options
| Option | Type | Default | Description |
|---|---|---|---|
apiKey | string | - | Your Google Maps API key (required). |
libraries | string[] | ['places'] | Google Maps libraries to load. |
language | string | - | Language for controls and labels (e.g., 'en', 'ja'). |
region | string | - | Region biasing (e.g., 'US', 'JP'). |
v | string | - | API version: 'weekly', 'quarterly', 'beta', or 'alpha'. Omitted by default (Google defaults to 'weekly'). |
Return Values
| Property | Type | Description |
|---|---|---|
onLoaded | (fn) => void | Callback after the loader script finishes. Receives { maps: Promise<typeof google.maps> }; await maps for the API callback. |
load | () => Promise<GoogleMapsApi> | Manually trigger script loading. |
status | Ref<string> | Current loading status ('awaitingLoad', 'loading', 'loaded', 'error', or 'removed'). |
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',
})
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 an additional library at runtime. The registry already requests places by default, so this example imports geometry:
<script setup lang="ts">
const { onLoaded } = useScriptGoogleMaps({
apiKey: 'key',
})
onMounted(() => {
onLoaded(async (instance) => {
const maps = await instance.maps
const geometry = await maps.importLibrary('geometry')
console.log(geometry.spherical)
})
})
</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.
Google removed the Drawing Library and Heatmap Layer from Maps JavaScript API 3.65 in May 2026. Although current project types still mention
drawing and visualization, do not use them for new integrations. See Google's completed deprecations. On this page