It's the 15th anniversary of Google Maps Platform - Check out the latest news and announcements

Best Practices

JS Best Practices

The Maps JavaScript API only works with a standard ECMAScript and W3C DOM environment. This means that modifying or overriding the behavior of the built-in classes and objects provided by the browser could make the Maps JavaScript API non-functional. Sometimes other libraries can conflict with the Maps JavaScript API by changing the behavior of the browser so that it is no longer a standard ECMAScript environment. The Maps JavaScript API is not compatible with those libraries.

Libraries that are known to be incompatible with the Maps JavaScript API:

  • Prototype: overrides Array.from() in a non-standard way.
  • MooTools (older versions): overrides Array.from() in a non-standard way.
  • DateJS (older versions): overrides Date.now() in a non-standard way.

Sometimes it is possible to modify incompatible libraries to remove the non-standard overrides.

CSS Best Practices

When you add or customize a map with the Maps JavaScript API, some of the styles you apply to your webpage may override your map styles and cause CSS conflicts. If you use a CSS framework or a JavaScript component for styling, this might add additional CSS conflicts with your map styles.

CSS frameworks and JavaScript styling components often use a CSS reset or a normalizer to handle rendering differences between browsers. Frameworks often use the box-sizing element to scale the margins and borders of web page elements. This usually involves changing the default browser behavior from using content-box to border-box.

This type of CSS reset can cause CSS conflicts with the Maps JavaScript API because the API doesn’t support changes to the user agent stylesheet. Additional CSS conflicts can occur if the framework or component references CSS classes or DOM elements of the Maps JavaScript API.

To avoid these conflicts, we have several recommendations to consider.

Specificity

Embedded and linked CSS is applied to your map before the Google maps styles. If all of your page styles are defined in embedded or linked CSS, follow the specificity rules to ensure that the correct styles are applied to your map.

Common CSS elements, such img, button, and a can be overwritten by the styles of your page. One of the most common scenarios is when the max-width attribute of the img element is set to 100 percent. This can cause distorted or hidden map components, especially if you're using InfoWindow.

To fix this issue, you can update the img element for your map so the max-width attribute is set to none. For exmample:

#map img
{
    max-width : none;
}

Class names

Don't reference class names and internal DOM elements of the JavaScript Maps API. This is not supported and can cause breaking changes in your website without notice. Instead, we recommend that you create your own CSS classes as containers for your map.

If a CSS framework or JavaScript component uses these type of references, our box-sizing override recommendation might serve as a work-around.

CSS box-sizing override

CSS box-sizing overrides provide a possible workaround for maps styling conflicts. This can be especially useful if you're using a CSS framework or JavaScript styling component. For example, if box-sizing is set to border-box, try the following:

  • Create a box-sizing override that sets the <html> element to border-box.
  • Use box-sizing: inherit for all elements other than your map.
  • Create a custom map container that resets the box-sizing element to initial.

CSS example:

html {
  box-sizing: border-box;
}

*,
*::before,
*::after {
  box-sizing: inherit;
}

.container-map {
  box-sizing: initial;
}