Skip to main content
Api

<ScriptGoogleMapsStaticMap>

Copy for LLMs

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

PropTypeDefaultDescription
centerstring | { lat: number, lng: number }Map center as an address, a "lat,lng" string, or a LatLngLiteral.
zoomnumber15Zoom level (0 to 21).
size`${number}x${number}`autoExplicit pixel size for the API request. When omitted, measures the rendered container on mount. Falls back to 640x400 during SSR.
scale1 | 22Device pixel ratio.
formatStaticMapFormatImage format: png, jpg, gif, png8, png32, jpg-baseline.
maptypeStaticMapTypeMap type: roadmap, satellite, terrain, hybrid.
mapIdstringCloud-based map styling ID.
markersstring | string[]Marker descriptors.
pathstring | string[]Polyline path descriptors.
visiblestring | string[]Locations that should be visible on the map.
stylestring | string[] | MapTypeStyle[]Map styling. Accepts raw Static Maps API style strings or Google Maps JS API MapTypeStyle[] objects.
languagestringLanguage code for map labels.
regionstringRegion bias.
signaturestringGoogle Maps URL signature for a direct request. Use it with an explicit apiKey; a signature does not replace the key.
apiKeystringAPI key override. Falls back to the public googleMaps registry key when omitted.
widthnumber | string640CSS width for the container.
heightnumber | string400CSS height for the container.
loading'eager' | 'lazy''lazy'Image loading strategy.
objectFitstring'cover'Object-fit for the <img> within its container.
imgAttrsImgHTMLAttributesAdditional attributes for the <img> element.

Size Handling

When size is not provided, the component:

  1. Client-side: Measures the container's pixel dimensions on mount and clamps to the Static Maps API limit of 640x640 (preserving aspect ratio).
  2. SSR: Derives from width/height props if both are pixel values.
  3. 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>
Was this page helpful?
Edit this page
Markdown For LLMs

useScriptGoogleMaps()

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

<ScriptGoogleMapsMarker>

Add a reactive advanced marker with optional custom Vue content.