A [`popover`](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#PopoverElement)
displays content (usually text or images) in a dialog window above the map, at a
given location. The popover has a content area and a tapered stem. The tip of
the stem is attached to a specified location on the map. Popovers appear as a
dialog to screen readers.


<iframe src="https://maps-docs-team.web.app/samples/3d-popover-location/dist/" allow="fullscreen; "></iframe>

Typically you will attach a popover to an [interactive
marker](https://developers.google.com/maps/documentation/javascript/3d/marker-overview#interactive_markers),
but you can also attach a popover to a specific `LatLngAltitude` coordinate, or
offset
it from a marker.

## Add a popover

The
[`PopoverElement`](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#PopoverElement)
constructor takes an
[`PopoverElementOptions`](https://developers.google.com/maps/documentation/javascript/reference/3d-map.md.txt#PopoverElementOptions)
object literal, which specifies the initial parameters for displaying the
popover.

The `PopoverElementOptions` object literal contains the following fields:

- `positionAnchor`: The `LatLngAltitude` position at which to display the marker. If using a marker, the marker's position will be used instead.
- `altitudeMode`: How the popover's altitude is interpreted.
- `lightDismissDisabled`: Whether the popover stays open when the user clicks outside of it, or presses the `Esc` key. When this option is set to `true`, multiple `lightDismissDisabled` popovers can be shown on the map simultaneously.
- `open`: Dictates whether the popover should be open or not. Defaults to `false`.

The content of the `PopoverElement` may contain a string of text, a snippet of
HTML, or a DOM element. You set the content by appending it to the
`PopoverElement` explicitly in the `header` or `default` slot.

If you want to explicitly size the content, you can put it in a `<div>` element
and style the `<div>` with CSS. Popovers are scrollable by default, and have a
predefined maximum height.

> [!IMPORTANT]
> **Important:** For the best user experience, only one popover should be open on the map at any one time. Multiple popovers make the map appear cluttered. If you only need one popover at a time, you can create just one `PopoverElement` object and open it at different locations or markers on map events, such as user clicks. If you do need more than one popover, you can display multiple `PopoverElement` objects at the same time by setting `lightDismissDisabled` to `true`.

## Anchor a popover to a LatLngAltitude coordinate

When you create a popover, it is not displayed automatically on the map. To
make the popover visible, you must set the `open` option to `true` in the
`PopoverElement`. You are able to perform this action during construction or
after instantiation.


```javascript
async function init() {
    const { Map3DElement, PopoverElement } =
        await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
        center: { lat: 37.8204, lng: -122.4783, altitude: 0.407 },
        range: 4000,
        tilt: 74,
        heading: 38,
        mode: 'HYBRID',
    });

    const popover = new PopoverElement({
        altitudeMode: 'ABSOLUTE',
        open: true,
        positionAnchor: { lat: 37.819852, lng: -122.478549, altitude: 150 },
    });

    popover.append('Golden Gate Bridge');

    map.append(popover);

    document.body.append(map);
}

void init();
```

<br />

## Anchor a popover to a marker

You can anchor popovers to markers. When adding a popover anchored to a marker,
you set the `PopoverElement.positionAnchor` option to use the marker.


```javascript
async function init() {
    const { Map3DElement, Marker3DInteractiveElement, PopoverElement } =
        await google.maps.importLibrary('maps3d');

    const map = new Map3DElement({
        center: { lat: 37.8204, lng: -122.4783, altitude: 0.407 },
        range: 4000,
        tilt: 74,
        heading: 38,
        mode: 'HYBRID',
    });

    // Popovers can only be added to interactive Markers
    const interactiveMarker = new Marker3DInteractiveElement({
        altitudeMode: 'ABSOLUTE',
        position: { lat: 37.819852, lng: -122.478549, altitude: 100 },
    });

    const popover = new PopoverElement({
        open: false,
        positionAnchor: interactiveMarker,
    });

    popover.append('Golden Gate Bridge');

    interactiveMarker.addEventListener('gmp-click', () => {
        // toggle the marker to the other state (unlee you are clicking on the marker itself when it reopens it)
        popover.open = !popover.open;
    });

    map.append(interactiveMarker);
    map.append(popover);

    document.body.append(map);
}

void init();
```

<br />

### Anchor a popover to a marker using HTML

You can also anchor popovers to markers without writing any JavaScript code, as
shown below:

```html
<gmp-map-3d mode="hybrid" center="37.819852,-122.478549" tilt="75" range="2000" heading="330">
  <gmp-marker-3d-interactive gmp-popover-target="my-popover" position="37.819852,-122.478549,100"></gmp-marker-3d-interactive>
  <gmp-popover id="my-popover">
    Golden Gate Bridge
  </gmp-popover>
</gmp-map-3d>
<script async src="https://maps.googleapis.com/maps/api/js?key=AIzaSyDGl0teQ6qwaBEdHazOWIEXd8XGWOZvoaM&v=beta&libraries=maps3d">
</script>
```

## Add custom content to a popover

You can add custom content to popovers by setting the `header` and `content`
options:

```javascript
async function init() {
  const {Map3DElement, MapMode, PopoverElement, AltitudeMode} = await google.maps.importLibrary('maps3d');

  const map = new Map3DElement({
    center: { lat: 37.819852, lng: -122.478549, altitude: 2000 },
    tilt: 75,
    heading: 330,
    mode: MapMode.SATELLITE,
  });
const popover = new PopoverElement({
altitudeMode: AltitudeMode.ABSOLUTE,
open: true,
positionAnchor: {lat: 37.819852, lng: -122.478549, altitude: 100},
});
const header = document.createElement('div');
header.style.fontWeight = 'bold';
header.slot = 'header';
header.textContent = 'Golden Gate Bridge';
const content = document.createElement('div');
content.textContent = 'Iconic orange bridge connecting San Francisco to Marin.';
popover.append(header);
popover.append(content);
document.body.append(map);
map.append(popover);
}

init();
```