Guides

Map Styling

Copy for LLMs

Google Maps supports two styling approaches: legacy JSON styles and cloud-based map IDs. Both work with Nuxt Scripts, including the static map placeholder.

JSON Styles

Use the mapOptions.styles prop with a JSON style array. You can find pre-made styles on Snazzy Maps.

Styles apply to both the static map placeholder and the interactive map.

JSON styles cannot combine with ScriptGoogleMapsMarker. AdvancedMarkerElement requires a mapId, and Google Maps treats styles and mapId as mutually exclusive. If the map contains markers, use cloud-based map IDs instead.
<script setup lang="ts">
const mapOptions = {
  styles: [
    {
      elementType: 'labels',
      stylers: [{ visibility: 'off' }, { color: '#f49f53' }],
    },
    {
      featureType: 'landscape',
      stylers: [{ color: '#f9ddc5' }, { lightness: -7 }],
    },
    {
      featureType: 'road',
      stylers: [{ color: '#813033' }, { lightness: 43 }],
    },
    {
      featureType: 'water',
      stylers: [
        { color: '#1994bf' },
        { saturation: -69 },
        { gamma: 0.99 },
        { lightness: 43 },
      ],
    },
    {
      featureType: 'poi.park',
      stylers: [{ color: '#645c20' }, { lightness: 39 }],
    },
  ],
}
</script>

<template>
  <ScriptGoogleMaps :map-options="mapOptions" />
</template>

Cloud-Based Map IDs

Google's Map Styling lets you create and manage styles in the Google Cloud Console, then apply them with a map ID.

<template>
  <ScriptGoogleMaps
    :map-options="{ mapId: 'YOUR_MAP_ID' }"
    :center="{ lat: -33.8688, lng: 151.2093 }"
    :zoom="12"
  />
</template>
JSON styles and mapId are mutually exclusive. When both are set, Google Maps keeps mapId and ignores styles. Because ScriptGoogleMapsMarker uses AdvancedMarkerElement (which requires a mapId), cloud-based map IDs are the only way to style a map that contains markers.

Dark Mode / Color Mode

Switch map styles automatically based on the user's color mode preference. Provide a mapIds object with light and dark map IDs:

<template>
  <ScriptGoogleMaps
    :map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
    :center="{ lat: -33.8688, lng: 151.2093 }"
    :zoom="12"
  />
</template>

If you set up a single Map ID in Google Cloud Console with both Light and Dark color schemes, point both keys at the same id and the map will pick up Google's colorScheme automatically:

<template>
  <ScriptGoogleMaps
    :map-ids="{ light: 'YOUR_MAP_ID', dark: 'YOUR_MAP_ID' }"
    :center="{ lat: -33.8688, lng: 151.2093 }"
    :zoom="12"
  />
</template>
Google Maps treats both mapId and colorScheme as init-only options. Toggling color mode tears down and re-creates the basic Map instance; Google does not support changing these without re-rendering. The component preserves the user's pan/zoom and remounts child components (markers, info windows, overlays) against the new map automatically.If you create resources imperatively from the exposed map ref (rather than via child components), listen for the @ready event; it re-fires after every re-init so you can re-attach them to the new map instance.

This auto-detects @nuxtjs/color-mode if installed. You can also control it manually with the colorMode prop:

<script setup lang="ts">
const isDark = ref(false)
</script>

<template>
  <ScriptGoogleMaps
    :map-ids="{ light: 'LIGHT_MAP_ID', dark: 'DARK_MAP_ID' }"
    :color-mode="isDark ? 'dark' : 'light'"
  />
  <button @click="isDark = !isDark">
    Toggle Dark Mode
  </button>
</template>

See Markers & Info Windows for combining styled maps with custom marker content.

Edit this page
Markdown For LLMs

Performance

ScriptGoogleMaps is optimized by default: the JavaScript API only loads when the user interacts with the map. Before that, a lightweight static image placeholder is shown.

Example: Markers & Info Windows