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 (preserving the user's pan/zoom). Child components (markers, info windows, overlays) are remounted against the new map automatically.

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