## JS Best Practices

### Override behavior and library compatibility

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()` and `Element.prototype.remove()` in non-standard ways.
- 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.

### Internal performance optimization

To improve page load speeds, the Maps JavaScript API may internally defer
loading interactive content until the element or container approaches the
viewport. These internal optimizations are subject to change at any time,
without notice. They are designed as a performance enhancement, and shouldn't be
used as a mechanism for managing billing. To ensure billing is not incurred
until an element is visible, defer its creation in your application code.

## 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.

> [!NOTE]
> **Note:** To verify the styles that the browser applies to each HTML element, see [Chrome DevTools CSS Reference](https://developers.google.com/web/tools/chrome-devtools/css/reference).

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](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity)
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](https://developers.google.com/maps/documentation/javascript/infowindows.md.txt).

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

```css
#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:

```css
html {
  box-sizing: border-box;
}

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

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