Migrate to advanced markers

  • google.maps.Marker is deprecated as of February 21st, 2024 (v3.56) and developers should transition to google.maps.marker.AdvancedMarkerElement.

  • Advanced markers require adding the marker library, changing the class name, and including a map ID during map initialization.

  • Developers can customize advanced markers with features like adjustable size, custom colors, graphic images, and HTML/CSS composition.

  • Several resources are available to learn more about advanced marker features such as basic customization, graphic markers, HTML/CSS markers, collision behavior, and accessibility.

As of February 21st, 2024 (v3.56), google.maps.Marker is deprecated. We encourage you to transition to the new google.maps.marker.AdvancedMarkerElement class. Advanced markers provide substantial improvements over the legacy google.maps.Marker class. Learn more about this deprecation

To update a legacy marker to be an advanced marker, take the following steps:

  1. Add code to import the marker library (see steps below).
  2. Change google.maps.Marker to google.maps.marker.AdvancedMarkerElement; if your import statement declares AdvancedMarker, you can omit the qualified path.
  3. Add a map ID to your map initialization code. For example mapId: 'DEMO_MAP_ID' for testing purposes if you don't have a map ID already.

Add the Advanced Marker library

The method you use for loading libraries depends on how your web page loads the Maps JavaScript API.

  • If your web page uses dynamic library import, add the markers library and import AdvancedMarkerElement (and optionally PinElement) at runtime, as shown here.

    const { AdvancedMarkerElement, PinElement } = await google.maps.importLibrary("marker");

  • If your web page uses the legacy direct script loading tag, add libraries=marker to the loading script, as shown in the following snippet.

    <script
src="https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&callback=initMap&v=weekly&libraries=marker"
defer
></script>

Learn more about loading the Maps JavaScript API

Examples

The following code examples show code for adding a legacy marker, followed by the code for the same example using advanced markers:

Before migration

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

const map = new google.maps.Map(document.getElementById("map"), {
  zoom: 4,
  center: position,
});

// The marker, positioned at Uluru
const marker = new google.maps.Marker({
  map: map,
  position: position,
  title: 'Uluru',
});

After migration

// Import the needed libraries.
// Not required if the legacy direct script loading tag is in use.
const { Map } = await.google.maps.importLibrary("maps");
const { AdvancedMarkerElement } = await google.maps.importLibrary("marker");

// The location of Uluru
const position = { lat: -25.344, lng: 131.031 };

const map = new Map(document.getElementById("map"),  {
  zoom: 4,
  center: position,
  mapId: "DEMO_MAP_ID", // Map ID is required for advanced markers.
});

// The advanced marker, positioned at Uluru
const marker = new AdvancedMarkerElement({
    map,
    position: position,
    title: 'Uluru/Ayers Rock',
});

Explore advanced marker features

Advanced markers can be customized in ways that were not possible before. Now you can adjust the size (scale) of markers, and change the colors of the background, border, and glyph. Custom graphic images are simpler to work with, and it is now possible to compose custom markers using HTML and CSS. Learn more about everything you can do with advanced markers: