Migrate to advanced markers

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. Note that the previous version of markers (google.maps.Marker) does not have this requirement.
  2. Change google.maps.Marker to google.maps.marker.AdvancedMarkerElement
  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 script loading, 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

  // 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,
    mapId: "DEMO_MAP_ID", // Map ID is required for advanced markers.
  });

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

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: