Api

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

Usage

Standalone

Display a static map without loading the interactive Google Maps JavaScript API.

<template>
  <ScriptGoogleMapsStaticMap
    center="51.95,19.13"
    :zoom="7"
    width="100%"
    height="300"
  />
</template>

As Placeholder

Use inside <ScriptGoogleMaps> to show a static map while the interactive map loads.

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

Props

Prop	Type	Default	Description
`center`	`string \| { lat: number, lng: number }`		Map center as an address, a `"lat,lng"` string, or a `LatLngLiteral`.
`zoom`	`number`	`15`	Zoom level (0 to 21).
`size`	`${number}x${number}`	auto	Explicit pixel size for the API request. When omitted, measures the rendered container on mount. Falls back to `640x400` during SSR.
`scale`	`1 \| 2`	`2`	Device pixel ratio.
`format`	`StaticMapFormat`		Image format: `png`, `jpg`, `gif`, `png8`, `png32`, `jpg-baseline`.
`maptype`	`StaticMapType`		Map type: `roadmap`, `satellite`, `terrain`, `hybrid`.
`mapId`	`string`		Cloud-based map styling ID.
`markers`	`string \| string[]`		Marker descriptors.
`path`	`string \| string[]`		Polyline path descriptors.
`visible`	`string \| string[]`		Locations that should be visible on the map.
`style`	`string \| string[] \| MapTypeStyle[]`		Map styling. Accepts raw Static Maps API style strings or Google Maps JS API `MapTypeStyle[]` objects.
`language`	`string`		Language code for map labels.
`region`	`string`		Region bias.
`signature`	`string`		Google Maps URL signature for a direct request. Use it with an explicit `apiKey`; a signature does not replace the key.
`apiKey`	`string`		API key override. Falls back to the public `googleMaps` registry key when omitted.
`width`	`number \| string`	`640`	CSS width for the container.
`height`	`number \| string`	`400`	CSS height for the container.
`loading`	`'eager' \| 'lazy'`	`'lazy'`	Image loading strategy.
`objectFit`	`string`	`'cover'`	Object-fit for the `<img>` within its container.
`imgAttrs`	`ImgHTMLAttributes`		Additional attributes for the `<img>` element.

Size Handling

When size is not provided, the component:

Client-side: Measures the container's pixel dimensions on mount and clamps to the Static Maps API limit of 640x640 (preserving aspect ratio).
SSR: Derives from width/height props if both are pixel values.
Fallback: Uses 640x400.

Set size explicitly to bypass auto-measurement.

API Key Security

The component loads the image directly from maps.googleapis.com. Restrict the key to your website and the Maps Static API before production use. See Google Maps Platform security guidance.

Google digital signatures cover the exact request URL. When passing signature, also pass an explicit size and keep every signed parameter stable. Generate the signature on a trusted server. Never expose the URL signing secret to the browser.

Slots

default

Override the <img> element with a custom template. Receives { src } with the computed Static Maps URL.

<template>
  <ScriptGoogleMapsStaticMap center="51.95,19.13" :zoom="7">
    <template #default="{ src }">
      <img :src="src" alt="Custom static map" class="rounded-lg shadow">
    </template>
  </ScriptGoogleMapsStaticMap>
</template>

Edit this page

Markdown For LLMs

useScriptGoogleMaps()

Load the Google Maps SDK and access its API directly from a composable.

Add a reactive advanced marker with optional custom Vue content.

On this page

Usage
Props
Size Handling
API Key Security
Slots