Skip to main content

<Popover> Component

A component to add a PopoverElement to a 3D map. Popovers are overlay elements similar to InfoWindows for 2D maps, used to display contextual information at a specific location or anchored to a marker on a Map3D.

Any JSX element added to the Popover component as children will get rendered into the content area of the popover.

Usage​

The Popover component must be used within an <APIProvider> that also contains a <Map3D> component.

Basic Example​

Display a popover at a specific position on the 3D map:

import {APIProvider, Map3D, Popover} from '@vis.gl/react-google-maps';

const App = () => {
  const [isOpen, setIsOpen] = useState(true);

  return (
    <APIProvider apiKey={'Your API key here'}>
      <Map3D
        defaultCenter={{lat: 37.7749, lng: -122.4194, altitude: 500}}
        defaultRange={2000}
        defaultTilt={60}>
        <Popover
          position={{lat: 37.7749, lng: -122.4194}}
          open={isOpen}
          onClose={() => setIsOpen(false)}>
          <div style={{padding: '8px'}}>
            <h3>San Francisco</h3>
            <p>Welcome to the city by the bay!</p>
          </div>
        </Popover>
      </Map3D>
    </APIProvider>
  );
};

Popover Anchored to a Marker​

A more typical use-case is to have a popover shown when clicking on a marker. You can anchor the popover to a Marker3DInteractiveElement using the anchor prop:

import {APIProvider, Map3D, Marker3D, Popover} from '@vis.gl/react-google-maps';

const MarkerWithPopover = ({position}) => {
  const [markerElement, setMarkerElement] = useState(null);
  const [popoverOpen, setPopoverOpen] = useState(false);

  return (
    <>
      <Marker3D
        ref={setMarkerElement}
        position={position}
        onClick={() => setPopoverOpen(true)}
        title="Click for more info"
      />

      {markerElement && (
        <Popover
          anchor={markerElement}
          open={popoverOpen}
          onClose={() => setPopoverOpen(false)}>
          <div style={{padding: '12px'}}>
            <h3>Location Info</h3>
            <p>This popover is anchored to the marker.</p>
          </div>
        </Popover>
      )}
    </>
  );
};

Content and Header​

The content provided as children to the Popover component is rendered into the main content area of the popover. Additionally, the headerContent prop can be used to render DOM elements into the separate header slot of the gmp-popover web component.

Light Dismiss Behavior​

By default, popovers can be closed by clicking outside of them ("light dismiss"). You can disable this behavior with the lightDismissDisabled prop:

<Popover
  position={{lat: 37.7749, lng: -122.4194}}
  open={isOpen}
  lightDismissDisabled>
  <div>This popover won't close when clicking outside</div>
</Popover>

To track the current visibility of the popover, you also have to add an onClose callback. This will get called when the popover is automatically closed by the maps API.

note

When lightDismissDisabled is true, you must provide another way for users to close the popover, such as a close button inside the content.

Automatic Panning​

By default, the map pans to make sure the popover is fully visible when it opens. This can cause conflicts when you want to have a fully controlled map state. In this case, this can be disabled using the autoPanDisabled prop.

import {Popover, AltitudeMode} from '@vis.gl/react-google-maps';

<Popover
  position={{lat: 37.7749, lng: -122.4194}}
  altitudeMode={AltitudeMode.RELATIVE_TO_GROUND}
  
>
  <div>Popover content!</div>
</Popover>;

Popover with Altitude​

Position a popover at a specific altitude above the ground:

import {Popover, AltitudeMode} from '@vis.gl/react-google-maps';

<Popover
  position={{lat: 37.7749, lng: -122.4194, altitude: 100}}
  altitudeMode={AltitudeMode.RELATIVE_TO_GROUND}
  open={isOpen}>
  <div>Floating 100m above ground!</div>
</Popover>;

Props​

The PopoverProps type extends google.maps.maps3d.PopoverElementOptions with additional React-specific props.

Required​

There are no strictly required props, but either position or anchor must be set for the popover to appear on the map.

Positioning Props​

position: google.maps.LatLngLiteral | google.maps.LatLngAltitudeLiteral​

The position at which to display this popover. Can include an optional altitude property.

// 2D position
<Popover position={{lat: 37.7749, lng: -122.4194}} open={true}>
  Content here
</Popover>

// 3D position with altitude
<Popover position={{lat: 37.7749, lng: -122.4194, altitude: 50}} open={true}>
  Content here
</Popover>
note

When an anchor is specified, the position prop will be ignored.

anchor: google.maps.maps3d.Marker3DInteractiveElement​

A Marker3DInteractiveElement instance to anchor the popover to. When specified, the popover will be positioned relative to the marker.

<Marker3D
  ref={setMarkerElement}
  position={position}
  onClick={() => setOpen(true)}
/>

<Popover anchor={markerElement} open={isOpen}>
  Anchored content
</Popover>

anchorId: string​

A string ID referencing a Marker3DInteractiveElement to anchor the popover to. This is an alternative to using the anchor prop when you have the marker's ID.

altitudeMode: AltitudeMode​

Specifies how the altitude component of the position is interpreted.

import {Popover, AltitudeMode} from '@vis.gl/react-google-maps';

<Popover
  position={{lat: 37.7749, lng: -122.4194, altitude: 100}}
  altitudeMode={AltitudeMode.RELATIVE_TO_GROUND}
  open={true}>
  Content here
</Popover>;

Available values:

  • ABSOLUTE: Altitude relative to mean sea level.
  • CLAMP_TO_GROUND: Popover is placed on the ground (default).
  • RELATIVE_TO_GROUND: Altitude relative to the ground surface.
  • RELATIVE_TO_MESH: Altitude relative to the highest surface (ground, buildings, or water).

Visibility Props​

open: boolean​

Whether the popover is currently visible. Defaults to false.

const [isOpen, setIsOpen] = useState(false);

<Popover position={position} open={isOpen}>
  Content here
</Popover>;

lightDismissDisabled: boolean​

When true, prevents the popover from being closed when clicking outside of it. Defaults to false.

<Popover position={position} open={true} lightDismissDisabled>
  This popover won't close on outside click
</Popover>

Events​

onClose: (event: Event) => void​

Called when the popover is closed via light dismiss (clicking outside the popover). Use this to keep your state in sync with the popover's visibility.

const [isOpen, setIsOpen] = useState(true);

<Popover position={position} open={isOpen} onClose={() => setIsOpen(false)}>
  Content here
</Popover>;
note

The onClose event only fires when the popover is closed via light dismiss. It will not fire when you programmatically set open={false}.

Ref​

The Popover component supports a ref that exposes the underlying google.maps.maps3d.PopoverElement instance:

import {useRef} from 'react';
import {Popover} from '@vis.gl/react-google-maps';

const MyComponent = () => {
  const popoverRef = useRef<google.maps.maps3d.PopoverElement>(null);

  const handleToggle = () => {
    if (popoverRef.current) {
      popoverRef.current.open = !popoverRef.current.open;
    }
  };

  return (
    <Popover ref={popoverRef} position={position}>
      Content here
    </Popover>
  );
};