Places UI Kit: A ready-to-use library that provides room for customization and low-code development. Try it out, and share yourinput on your UI Kit experience.

Best Practices

  • Avoid using JavaScript libraries like Prototype, MooTools (older versions), and DateJS (older versions) as they can conflict with the Maps JavaScript API due to their non-standard overrides of built-in browser functionalities.

  • Prevent CSS conflicts by following specificity rules and avoiding direct references to Maps JavaScript API class names or internal DOM elements; instead, use custom CSS classes as containers for your map.

  • If using CSS frameworks or components that cause conflicts, consider a box-sizing override: set the<html> element toborder-box, usebox-sizing: inherit for other elements, and resetbox-sizing toinitial for your custom map container.

  • Common CSS elements likeimg,button, anda can be overwritten by page styles, potentially causing distorted or hidden map components; adjust styles accordingly, for example, settingmax-width: none for map images to avoid issues.

JS Best Practices

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

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

  • Prototype: overridesArray.from() andElement.prototype.remove() in non-standard ways.
  • MooTools (older versions): overridesArray.from() in a non-standard way.
  • DateJS (older versions): overridesDate.now() in a non-standard way.

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

CSS Best Practices

When you add or customize a map with the Maps JavaScript API, some of the stylesyou 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 addadditional CSS conflicts with your map styles.

Note: To verify the styles that the browser applies to each HTML element, seeChrome DevTools CSS Reference.

CSS frameworks and JavaScript styling components often use a CSS reset or anormalizer to handle rendering differences between browsers. Frameworks oftenuse thebox-sizing element to scale the margins and borders of web pageelements. This usually involves changing the default browser behavior from usingcontent-box toborder-box.

This type of CSS reset can cause CSS conflicts with the Maps JavaScript APIbecause the API doesn’t support changes to the user agent stylesheet. AdditionalCSS conflicts can occur if the framework or component references CSS classes orDOM 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. Ifall of your page styles are defined in embedded or linked CSS, follow thespecificity rules to ensure that the correct styles are applied to your map.

Common CSS elements, suchimg,button, anda can be overwritten by thestyles of your page. One of the most common scenarios is when themax-widthattribute of theimg element is set to 100 percent. This can cause distortedor hidden map components, especially if you're usingInfoWindow.

To fix this issue, you can update theimg element for your map so themax-width attribute is set tonone. For example:

#mapimg{max-width:none;}

Class names

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

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

CSS box-sizing override

CSS box-sizing overrides provide a possible workaround for maps stylingconflicts. This can be especially useful if you're using a CSS framework orJavaScript styling component. For example, ifbox-sizing is set toborder-box, try the following:

  • Create abox-sizing override that sets the<html> element toborder-box.
  • Usebox-sizing: inherit for all elements other than your map.
  • Create a custom map container that resets thebox-sizing element toinitial.

CSS example:

html{box-sizing:border-box;}*,*::before,*::after{box-sizing:inherit;}.container-map{box-sizing:initial;}

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-11-21 UTC.