### Minimal InfoWindow Example

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/info-window

A basic example showing how to render an InfoWindow when the map is initially displayed. Note that this example does not provide a way to reopen the InfoWindow once closed.

```jsx
const MapWithInfoWindow = () => {
  return (
    <Map {...mapProps}>
      <InfoWindow position={infoWindowPosition}>
        The content of the info window is here.
      </InfoWindow>
    </Map>
  );
};

```

--------------------------------

### Minimal InfoWindow Example

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/info-window

A basic example demonstrating how to render an InfoWindow with content directly on the map. The InfoWindow will be initially shown but can be closed by the user.

```APIDOC
## `<InfoWindow>` Component

### Description
Displays small, temporary overlays on the map, typically used to show additional information for map locations like labels or images. InfoWindows can be freely positioned or anchored to a marker. Any JSX content provided as children will be rendered within the InfoWindow.

### Usage

#### Minimal Example
This example shows an InfoWindow that is initially displayed when the map renders. The user can close it, but there's no built-in mechanism to reopen it without managing state externally.

```jsx
const MapWithInfoWindow = () => {
  return (
    <Map {...mapProps}>
      <InfoWindow position={infoWindowPosition}>
        The content of the info window is here.
      </InfoWindow>
    </Map>
  );
};
```

#### Infowindow Attached to Marker
A common use case where an InfoWindow is shown upon clicking a marker. This involves a custom `MarkerWithInfoWindow` component that manages the InfoWindow's visibility based on marker interactions and map events.

```jsx
const MarkerWithInfoWindow = ({position}) => {
  const [markerRef, marker] = useAdvancedMarkerRef();
  const [infoWindowShown, setInfoWindowShown] = useState(false);

  const handleMarkerClick = useCallback(() => setInfoWindowShown(isShown => !isShown), []);
  const handleClose = useCallback(() => setInfoWindowShown(false), []);

  return (
    <>
      <AdvancedMarker
        ref={markerRef}
        position={position}
        onClick={handleMarkerClick}
      />

      {infoWindowShown && (
        <InfoWindow anchor={marker} onClose={handleClose}>
          <h2>InfoWindow content!</h2>
          <p>Some arbitrary html to be rendered into the InfoWindow.</p>
        </InfoWindow>
      )}
    </>
  );
};
```

### Props

#### Required Props
No props are strictly required, but either `position` or `anchor` must be provided to display the InfoWindow.

#### General Props

- **`position`** (google.maps.LatLngLiteral): The geographical coordinates where the InfoWindow will be displayed. This prop is ignored if an `anchor` is specified.
- **`anchor`** (google.maps.Marker | google.maps.marker.AdvancedMarkerElement): A Marker or AdvancedMarker instance to anchor the InfoWindow to. The InfoWindow will be positioned at the top-center of this anchor. References can be obtained using the `ref` property of `Marker` and `AdvancedMarker` components.
- **`zIndex`** (number): Controls the display order of InfoWindows, with higher values appearing in front. By default, InfoWindows are ordered by latitude, and they always appear in front of markers.
- **`pixelOffset`** ([number, number]): An offset in pixels from the tip of the InfoWindow to the anchor point on the map. If an InfoWindow is anchored, the offset is calculated from the anchor's top/center.
```

--------------------------------

### Setting Up Development Environment

Source: https://visgl.github.io/react-google-maps/docs/contributing

Installs dependencies and builds the project locally. Run these commands after cloning the repository.

```bash
git checkout main

npm install

npm run test
```

--------------------------------

### Install React Google Maps via npm

Source: https://visgl.github.io/react-google-maps/docs/get-started

Install the library using npm. This command adds the package to your project's dependencies.

```bash
npm install @vis.gl/react-google-maps

```

--------------------------------

### Install React Google Maps via yarn

Source: https://visgl.github.io/react-google-maps/docs/get-started

Install the library using yarn. This command adds the package to your project's dependencies.

```bash
yarn add @vis.gl/react-google-maps

```

--------------------------------

### InfoWindow Attached to Marker Example

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/info-window

Demonstrates a common use case where an InfoWindow is shown on click for a marker. This example includes handling marker clicks to toggle the InfoWindow and synchronizing state when the InfoWindow is closed by the map or user.

```jsx
const MarkerWithInfoWindow = ({position}) => {
  const [markerRef, marker] = useAdvancedMarkerRef();
  const [infoWindowShown, setInfoWindowShown] = useState(false);
  const handleMarkerClick = useCallback(
    () => setInfoWindowShown(isShown => !isShown),
    []
  );
  const handleClose = useCallback(() => setInfoWindowShown(false), []);
  return (
    <>
      <AdvancedMarker
        ref={markerRef}
        position={position}
        onClick={handleMarkerClick}
      />
      {infoWindowShown && (
        <InfoWindow anchor={marker} onClose={handleClose}>
          <h2>InfoWindow content!</h2>
          <p>Some arbitrary html to be rendered into the InfoWindow.</p>
        </InfoWindow>
      )}
    </>
  );
};

```

--------------------------------

### Marker3D Positioning Examples

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/marker-3d

Shows how to set the position for a Marker3D, including 2D coordinates and 3D coordinates with explicit altitude.

```javascript
// 2D position (altitude defaults based on altitudeMode)
<Marker3D position={{lat: 37.7749, lng: -122.4194}} />

// 3D position with explicit altitude
<Marker3D position={{lat: 37.7749, lng: -122.4194, altitude: 100}} />
```

--------------------------------

### Basic APIProvider Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/api-provider

This snippet shows the basic setup for the APIProvider component, requiring only the API key. It should be placed high in your component tree.

```javascript
import React from 'react';
import {APIProvider} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    {/* ... any components ... */}
  </APIProvider>
);

export default App;
```

--------------------------------

### Using useMapsLibrary Hook

Source: https://visgl.github.io/react-google-maps/docs/api-reference/hooks/use-maps-library

This example demonstrates how to use the `useMapsLibrary` hook to load the 'places' library and then instantiate a `Place` object. Ensure your component tree is wrapped with `APIProvider` and that both the library and map are available before proceeding.

```javascript
const MyComponent = () => {
  const map = useMap();
  const placesLib = useMapsLibrary('places');

  useEffect(() => {
    if (!placesLib || !map) return;

    const place = new placesLib.Place({ id: 'ChIJC8HakaIRkFQRiOgkgdHmqkk' }); // PLACE_ID

    // ...
  }, [placesLib, map]);

  // ...
};

// Make sure you have wrapped the component tree with the APIProvider
const App = () => (
  <APIProvider apiKey={/* ... */}>
    {/* ... */}
    <MyComponent />
  </APIProvider>
);
```

--------------------------------

### Polyline Component Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polyline

Basic example of how to use the Polyline component within the APIProvider and Map components.

```APIDOC
## `<Polyline>` Component

React component to display a Polyline on the map.

### Usage

```jsx
import React from 'react';
import { APIProvider, Map, Polyline } from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    <Map zoom={12} center={{ lat: 53.54992, lng: 10.00678 }}>
      <Polyline
        path={[
          { lat: 53.54, lng: 10.0 },
          { lat: 53.55, lng: 10.02 },
          { lat: 53.56, lng: 10.01 }
        ]}
        strokeColor={'#ff0000'}
        strokeWeight={3}
      />
    </Map>
  </APIProvider>
);

export default App;
```

### Props

The `PolylineProps` interface extends the `google.maps.PolylineOptions` interface and includes all possible options available for a Polyline.

#### Path Props

*   **`polyline`**: `google.maps.Polyline` - An existing `google.maps.Polyline` instance to use instead of creating a new one. When provided, all other props (path, options, event handlers) will still be applied to this instance.
*   **`path`**: `Array<google.maps.LatLng | google.maps.LatLngLiteral>` - The controlled path of the polyline.
*   **`defaultPath`**: `Array<google.maps.LatLng | google.maps.LatLngLiteral>` - The initial path of the polyline (uncontrolled).
*   **`encodedPath`**: string - An encoded polyline string. When provided, will be decoded and used as the path. Takes precedence over the `path` prop if both are specified.
    ```jsx
    <Polyline
      encodedPath="_p~iF~ps|U_ulLnnqC_mqNvxq`@"
      strokeColor={'#0088ff'}
      strokeWeight={4}
    />
    ```
    *Note: When using `encodedPath`, the geometry library will be automatically loaded.*

#### Event Props

*   **`onClick`**: `(e: google.maps.MapMouseEvent) => void` - Called when the polyline is clicked.
*   **`onDrag`**: `(e: google.maps.MapMouseEvent) => void` - Called repeatedly while the polyline is being dragged.
*   **`onDragStart`**: `(e: google.maps.MapMouseEvent) => void` - Called when dragging of the polyline begins.
*   **`onDragEnd`**: `(e: google.maps.MapMouseEvent) => void` - Called when dragging of the polyline ends.
*   **`onMouseOver`**: `(e: google.maps.MapMouseEvent) => void` - Called when the mouse enters the polyline.
*   **`onMouseOut`**: `(e: google.maps.MapMouseEvent) => void` - Called when the mouse leaves the polyline.
*   **`onPathChanged`**: `(path: google.maps.LatLng[]) => void` - Called when the path is changed (via dragging or editing vertices).

#### Style Props

All styling options from `google.maps.PolylineOptions` are supported:

*   `strokeColor`: string
*   `strokeOpacity`: number
*   `strokeWeight`: number
*   `geodesic`: boolean - When true, edges of the polyline are interpreted as geodesic arcs
*   `icons`: `google.maps.IconSequence[]` - Icons to render along the polyline

#### Behavior Props

*   `clickable`: boolean - Whether the polyline handles mouse events
*   `draggable`: boolean - Whether the polyline can be dragged
*   `editable`: boolean - Whether the polyline can be edited
*   `visible`: boolean - Whether the polyline is visible
*   `zIndex`: number - The z-index of the polyline

### Editable Polylines and Controlled / Uncontrolled State

The distinction between controlled and uncontrolled usage patterns is only relevant when the polyline is `editable` or `draggable`. When a polyline is editable, the Google Maps API automatically adds handles to the vertices on the map and handles all mouse events for those handles internally, allowing users to modify the shape directly.

```jsx
// Uncontrolled - initial value only, users can edit freely
<Polyline
    defaultPath={[{lat: 53.5, lng: 10}, {lat: 53.6, lng: 10.1}]}
    editable
/>

// Controlled - value always reflects props
<Polyline path={path} editable/>
```

When using controlled props with `editable` or `draggable`, you must use the `onPathChanged` callback to sync state, otherwise the polyline will snap back to its original position:

```jsx
const [path, setPath] = useState([
  {lat: 53.5, lng: 10},
  {lat: 53.6, lng: 10.1}
]);

<Polyline
  path={path}
  editable
  draggable
  onPathChanged={newPath => setPath(newPath.map(p => p.toJSON()))}
/>;
```
```

--------------------------------

### Basic Map Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/map

A basic example of how to render a Google Map using the Map component within an APIProvider. The map is initialized with a center and zoom level.

```APIDOC
## Basic Map Usage

### Description
This example demonstrates the fundamental usage of the `<Map>` component. It requires an `<APIProvider>` to be present in the component tree and is configured with essential camera properties: `center` and `zoom`.

### Method
N/A (React Component)

### Endpoint
N/A (React Component)

### Parameters
#### Props
- **apiKey** (string) - Required - The Google Maps API key, typically provided via environment variables.
- **center** (google.maps.LatLngLiteral) - Required - The initial latitude and longitude for the map's center.
- **zoom** (number) - Required - The initial zoom level for the map.
```

--------------------------------

### Minimal Map Example

Source: https://visgl.github.io/react-google-maps/docs/get-started

A basic React component that renders a Google Map. Ensure the API key is provided via APIProvider.

```jsx
import React from 'react';
import {createRoot} from 'react-dom/client';
import {APIProvider, Map} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={API_KEY}>
    <Map
      style={{width: '100vw', height: '100vh'}}
      defaultCenter={{lat: 22.54992, lng: 0}}
      defaultZoom={3}
      gestureHandling='greedy'
      disableDefaultUI
    />
  </APIProvider>
);

const root = createRoot(document.querySelector('#app'));
root.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

```

--------------------------------

### Initialize Firebase App Check with APIProvider

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/api-provider

This example shows how to create a custom wrapper component that initializes Firebase App Check and passes the token fetcher to the APIProvider. This is useful for protecting your Google Maps Platform API key.

```typescript
import React, {PropsWithChildren, useCallback} from 'react';

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

import {initializeApp} from 'firebase/app';

import {
  getToken,
  initializeAppCheck,
  ReCaptchaEnterpriseProvider
} from 'firebase/app-check';

// Firebase and App Check initialization
const app = initializeApp({/* ... */});
const appCheck = initializeAppCheck(firebaseApp, {
  provider: new ReCaptchaEnterpriseProvider(RECAPTCHA_SITE_KEY),
  isTokenAutoRefreshEnabled: true
});

// custom wrapper for the APIProvider
export function CustomAPIProvider({children, ...props}: PropsWithChildren<APIProviderProps>) {
  const fetchAppCheckToken = useCallback(() => getToken(appCheck, false), []);

  return (
    <APIProvider {...props} fetchAppCheckToken={fetchAppCheckToken}>
      {children}
    </APIProvider>
  );
}

```

--------------------------------

### Create and Render Static Map URL

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/static-map

Generates a URL for a Google Static Map using createStaticMapsUrl and renders it with the StaticMap component. Includes an example of server-side URL signing.

```javascript
import {StaticMap, createStaticMapsUrl} from '@vis.gl/react-google-maps';  

  
  const App = () => {  

  let staticMapsUrl = createStaticMapsUrl({
    apiKey: 'YOUR API KEY',
    width: 512,
    height: 512,
    center: {lat: 53.555570296010295, lng: 10.008892744638956},
    zoom: 15
  });
  

  // Recommended url-signing when in a server environment.  
  staticMapsUrl = someServerSigningCode(
    staticMapsUrl,
    process.env.MAPS_SIGNING_SECRET
  );
  

  return <StaticMap url={staticMapsUrl} />;

};

```

--------------------------------

### Using Encoded Paths

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polygon

Example of using the `encodedPaths` prop to define a polygon's geometry using encoded polyline strings.

```APIDOC
#### `encodedPaths`: string[]

```jsx
<Polygon
  encodedPaths={['_p~iF~ps|U_ulLnnqC_mqNvxq`@', 'gg~iF~|s|UaaJhMcBxY']}
  fillColor={'#0088ff'}
  fillOpacity={0.3}
/>
```

note
When using `encodedPaths`, the geometry library will be automatically loaded.
```

--------------------------------

### Polygon with Hole

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polygon

Example of creating a polygon with a hole by providing multiple paths.

```APIDOC
#### `paths`: `Array<Array<google.maps.LatLng | google.maps.LatLngLiteral>>`

```jsx
// Polygon with hole
<Polygon paths={[
    // Outer path
    [{lat: 53.54, lng: 10.0}, {lat: 53.55, lng: 10.02}, {
        lat: 53.56,
        lng: 10.01
    }],
    // Inner path (hole)
    [{lat: 53.545, lng: 10.005}, {lat: 53.55, lng: 10.015}, {
        lat: 53.555,
        lng: 10.008
    }]
]}/>
```
```

--------------------------------

### Accessing the Polygon Instance

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polygon

Demonstrates how to get a reference to the underlying google.maps.Polygon instance using `useRef`.

```APIDOC
## Extracting the Polygon Instance

### Description

You can access the underlying `google.maps.Polygon` instance via a ref to interact with it directly or call its methods.

### Usage

```jsx
import React, { useRef } from 'react';
import { Polygon } from '@react-google-maps/api';

function MyMapComponent() {
  const polygonRef = useRef(null);

  return (
    <Polygon
      ref={polygonRef}
      paths={[
        { lat: 53.54, lng: 10.0 },
        { lat: 53.55, lng: 10.02 },
        { lat: 53.56, lng: 10.01 }
      ]}
      // Other Polygon props...
    />
  );
}
```

### Accessing the Instance

After the component mounts, `polygonRef.current` will hold the `google.maps.Polygon` instance.
```

--------------------------------

### Basic Map3D Initialization

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/map-3d

Renders a basic 3D map with satellite imagery and initial camera settings. Ensure the API key is provided via environment variables.

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

const App = () => (
  <APIProvider apiKey={process.env.GOOGLE_MAPS_API_KEY}>
    <Map3D
      mode="SATELLITE"
      defaultCenter={{lat: 37.7749, lng: -122.4194, altitude: 1000}}
      defaultRange={5000}
      defaultHeading={0}
      defaultTilt={45}
    />
  </APIProvider>
);
```

--------------------------------

### useAdvancedMarkerRef Hook

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/advanced-marker

Provides a way to get a reference to the AdvancedMarker instance, useful for imperative actions or accessing its methods.

```APIDOC
## useAdvancedMarkerRef()

### Description
A hook to obtain a ref for the AdvancedMarker component.

### Usage
```jsx
const ref = useAdvancedMarkerRef();
<AdvancedMarker ref={ref} ... />
```

### Returns
- `ref`: A React ref object that can be attached to the AdvancedMarker component.
```

--------------------------------

### Basic Marker Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/marker

Demonstrates how to import and use the Marker component within an APIProvider and Map context. Ensure you replace 'Your API key here' with your actual Google Maps API key.

```javascript
import React, {FunctionComponent} from 'react';  

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

  

const App: FunctionComponent<Record<string, unknown>> = () => (  

  <APIProvider apiKey={'Your API key here'}>  

    <Map zoom={12} center={{lat: 53.54992, lng: 10.00678}}>  

      <Marker position={{lat: 53.54992, lng: 10.00678}} />  

    </Map>  

  </APIProvider>  

);  

export default App;  

```

--------------------------------

### APIProvider Component Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/api-provider

Demonstrates how to use the APIProvider component by providing the necessary API key. This component should typically be placed at the top of the application's component tree.

```APIDOC
## APIProvider Component

The `APIProvider` is our component to load the Google Maps JavaScript API. Besides that, it provides context information and functions for the other components and hooks of this library.

It can be added at any level of the application (typically somewhere at the top of your component-tree), and it will render all child components unmodified. A re-render is only triggered once the loading status of the Maps JavaScript API changes.

Normally, there should only be a single instance of the APIProvider in a page, but there are situations (e.g., multiple React render-roots in a page) where this isn't possible. In those cases, make sure to create all `APIProvider` components using the exact same props, since only the first one to render will actually load the maps API.

When the Maps JavaScript API has already been loaded externally (i.e., the `google.maps.importLibrary` function exists), the `APIProvider` will ignore all specified props and use the existing `importLibrary` function.

Important
The Maps JavaScript API can only be loaded once, and settings like the language and region cannot be changed after loading. Therefore, it is important to make sure the props are specified with their final values when the `APIProvider` component is first rendered. Changing these props after the first render will in most cases have no effect, cause an error, or both.

## Usage
The `APIProvider` only needs the Google Maps Platform API Key to function. This has to be provided via the `apiKey` prop:

```javascript
import React from 'react';
import {APIProvider} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    {/* ... any components ... */}
  </APIProvider>
);

export default App;
```

## Props
The props are based on the parameters available for the 'Dynamic Library Import' API which we are using under the hood.

note
Most of the props below are marked with 'first-render only', which refers to the fact that these can only be specified on first render, later changes to the values will have no effect.

### Required
#### `apiKey`: string (required, first-render only)

The API Key for the Maps JavaScript API.

### Optional
#### `version`: string (first-render only)

The version to load (defaults to `weekly`).

#### `region`: string (first-render only)

The region code to use. This alters the map's behavior based on a given country or territory. Quoting the official docs:

> As the developer of a Maps JavaScript API application, you are encouraged to always set a region parameter as various services (such as Places Autocomplete) tend to provide better results when the region is set.
> It is also your responsibility to ensure that your application complies with local laws by ensuring that the correct region localization is applied for the country in which the application is hosted.

#### `language`: string (first-render only)

The language to use. This affects all text-content on the map, and the responses to service requests. The default value is determined per user based on HTTP-headers sent by the Browser.

#### `authReferrerPolicy`: string (first-render only)

If your API key is configured for an entire subdomain, you can set `authReferrerPolicy: "origin"` to limit the amount of data sent when authorizing requests from the Maps JavaScript API.

#### `libraries`: string[]

A list of libraries to load immediately (libraries can also be loaded later with the `useMapsLibrary` hook).

#### `channel`: number

To track usage of Google Maps JavaScript API via numeric channels. The only acceptable channel values are numbers from 0-999. Read more in the documentation.

#### `solutionChannel`: string

To help Google to better understand types of usage of the Google Maps JavaScript API, the query parameter `solution_channel` can be set when loading the API.
The `@vis.gl/react-google-maps` library will by default set this to a generic value unique to this library (`GMP_VISGL_react`). You may opt out at any time by setting this prop to an empty string. Read more in the documentation.

#### `disableUsageAttribution`: boolean

To help Google understand which libraries and samples are helpful to developers, usage attribution IDs are sent with map requests by default. Set this prop to `true` to opt out of sending the usage attribution ID for this library.
Individual maps can still specify custom attribution IDs via the `internalUsageAttributionIds` prop on the `<Map>` component, which will be used even when this option is enabled.
Read more in the documentation.
```

--------------------------------

### Customizing AdvancedMarker with Pin

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/pin

Demonstrates how to use the Pin component to customize the appearance of an AdvancedMarker. Ensure AdvancedMarker is imported.

```javascript
const CustomizedMarker = () => (
  <AdvancedMarker position={{lat: 53.54992, lng: 10.00678}}>
    <Pin background={'#FBBC04'} glyphColor={'#000'} borderColor={'#000'} />
  </AdvancedMarker>
);
```

--------------------------------

### Running the Full Test Suite

Source: https://visgl.github.io/react-google-maps/docs/contributing

Executes all tests in the project to ensure code integrity. This is a required step before submitting pull requests.

```bash
npm run test
```

--------------------------------

### Accessing Polygon Instance with Ref

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polygon

This snippet demonstrates how to get a reference to the google.maps.Polygon instance using the `useRef` hook. This allows you to interact with the underlying map object directly.

```javascript
const polygonRef = useRef<google.maps.Polygon>(null);

<Polygon 
  ref={polygonRef}
  paths={[
    {lat: 53.54, lng: 10.0},
    {lat: 53.55, lng: 10.02},
    {lat: 53.56, lng: 10.01}
  ]} 
/>;
```

--------------------------------

### AdvancedMarker Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/advanced-marker

Demonstrates how to use the AdvancedMarker component with default pins, custom pins using the Pin component, and fully custom HTML content.

```APIDOC
## AdvancedMarker Component

A component to add an `AdvancedMarkerElement` to a map. By default, an AdvancedMarker will appear as a balloon-shaped, red maps-pin at the specified position on the map, but the appearance of the markers can be fully customized.

**Note:** The `AdvancedMarker` can only be used on maps using cloud-based map styling (i.e. the `Map`-component has a `mapId` specified).

### Usage

By default, the marker will be rendered as the default red balloon pin. This can be customized in two ways: by specifying custom colors, an icon and such via a `Pin` component, or by creating the complete marker with html/css (images, svg, animations are all supported).

For this, the `AdvancedMarker` component optionally accepts child components that will be rendered instead of the default pin-element on the map, making it possible to create simple labels and infowindows with it.

```javascript
import {AdvancedMarker} from './advanced-marker';

<Map {...mapProps}>
  {/* red default marker */}
  <AdvancedMarker position={{lat: 29.5, lng: -81.2}} />

  {/* customized green marker */}
  <AdvancedMarker position={{lat: 29.5, lng: -81.2}}>
    <Pin
      background={'#0f9d58'}
      borderColor={'#006425'}
      glyphColor={'#60d98f'}
    />
  </AdvancedMarker>

  {/* fully customized marker */}
  <AdvancedMarker position={{lat: 29.5, lng: -81.2}}>
    <img src={markerImage} width={32} height={32} />
  </AdvancedMarker>
</Map>;
```

When anything other than a `Pin` component is specified for the marker, a div element (the "content element") will be created and the children will be rendered into that content element via a portal. The `style` and `className` props can be used to configure the styling of this content element.

**Tip:** When custom html is specified, the marker will be positioned such that the `position` on the map is at the bottom center of the content-element. If you need it positioned differently, you can use the `anchorPoint` property of the `AdvancedMarker`. For example, to have the anchor point in the top-left corner of the marker:

```javascript
import {AdvancedMarker, AdvancedMarkerAnchorPoint} from '@vis.gl/react-google-maps';

<AdvancedMarker position={...} anchorPoint={AdvancedMarkerAnchorPoint.TOP_LEFT}>
    ...
</AdvancedMarker>;
```

### Props

The `AdvancedMarker` component supports most of the options in `google.maps.marker.AdvancedMarkerElementOptions` as props, as well as a couple of others that are specific to React.

#### Required

There are no strictly required props for the AdvancedMarker component, but – for obvious reasons – the position has to be set for the marker to be shown on the map.

#### Content Props

##### `className`: string

A className to be added to the markers content-element. The content-element is either an element that contains the custom HTML content or the DOM representation of the `google.maps.marker.PinElement` when a Pin or an empty AdvancedMarker component is rendered.

##### `style`: CSSProperties

Additional style-rules to apply to the content-element. Since the content-element isn't created when using the default-pin, this option is only available when using custom HTML markers.

##### `title`: string

The title of the marker. If provided, an accessibility text (e.g. for use with screen readers) will be added to the AdvancedMarkerElement with the provided value.

#### Positioning Props

##### `position`: google.maps.LatLngLiteral | google.maps.LatLngAltitudeLiteral

The position of the marker. For maps with tilt enabled, an `AdvancedMarker` can also be placed at an altitude using the `{lat: number, lng: number, altitude: number}` format.

##### `zIndex`: number

All markers are displayed on the map in order of their zIndex, with higher values in front of lower values. By default, `AdvancedMarker`s are displayed according to their vertical position on screen, with lower AdvancedMarkerElements appearing in front of AdvancedMarkerElements farther up the screen.

**Note:** The `zIndex` is also used to help determine relative priority between multiple markers when using collision behavior `CollisionBehavior.OPTIONAL_AND_HIDES_LOWER_PRIORITY`. A higher `zIndex` value indicates higher priority.
```

--------------------------------

### Basic Polygon Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polygon

Demonstrates the basic usage of the `<Polygon>` component to render a simple polygon on the map. Ensure you have imported the necessary components and provided an API key.

```javascript
import React from 'react';
import {APIProvider, Map, Polygon} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    <Map zoom={12} center={{lat: 53.54992, lng: 10.00678}}>
      <Polygon
        paths={[
          {lat: 53.54, lng: 10.0},
          {lat: 53.55, lng: 10.02},
          {lat: 53.56, lng: 10.01}
        ]}
        fillColor={'#0088ff'}
        fillOpacity={0.3}
        strokeColor={'#0088ff'}
        strokeWeight={2}
      />
    </Map>
  </APIProvider>
);

export default App;
```

--------------------------------

### Basic Map Rendering

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/map

Renders a basic Google Map. Ensure the API key is provided via environment variables and the component is wrapped in an APIProvider.

```jsx
import {APIProvider, Map} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={process.env.GOOGLE_MAPS_API_KEY}>
    <Map zoom={10} center={{lat: 53.54992, lng: 10.00678}} />
  </APIProvider>
);
```

--------------------------------

### Accessing Polyline Instance with Ref

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/polyline

Use the `useRef` hook to get a reference to the underlying `google.maps.Polyline` instance. This allows you to interact with the native Google Maps API object directly.

```javascript
const polylineRef = useRef<google.maps.Polyline>(null);

<Polyline 
  ref={polylineRef}
  path={[
    {lat: 53.54, lng: 10.0},
    {lat: 53.55, lng: 10.02}
  ]} 
/>;
```

--------------------------------

### Accessing Circle Instance with Ref

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/circle

Demonstrates how to get a reference to the underlying google.maps.Circle instance using the `useRef` hook. This allows direct interaction with the Google Maps API object.

```jsx
const circleRef = useRef<google.maps.Circle>(null);

<Circle ref={circleRef} center={{lat: 53.5, lng: 10}} radius={1000} />
```

--------------------------------

### Basic Circle Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/circle

Demonstrates how to render a basic circle on the map with specified center, radius, and styling. Ensure you have the APIProvider set up with your API key.

```jsx
import React from 'react';
import {APIProvider, Map, Circle} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    <Map zoom={12} center={{lat: 53.54992, lng: 10.00678}}>
      <Circle
        center={{lat: 53.54992, lng: 10.00678}}
        radius={1000}
        fillColor={'#0088ff'}
        fillOpacity={0.3}
        strokeColor={'#0088ff'}
        strokeWeight={2}
      />
    </Map>
  </APIProvider>
);

export default App;
```

--------------------------------

### Accessing Rectangle Instance with Ref

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/rectangle

Shows how to get a reference to the underlying `google.maps.Rectangle` instance using `useRef`. This allows direct interaction with the Google Maps API methods on the rectangle object.

```jsx
const rectangleRef = useRef<google.maps.Rectangle>(null);

<Rectangle
  ref={rectangleRef}
  bounds={{north: 53.56, south: 53.54, east: 10.03, west: 9.99}}
/>;
```

--------------------------------

### Marker Component Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/marker

Demonstrates how to use the Marker component within the APIProvider and Map components to display a marker at a specific position.

```APIDOC
## `<Marker>` Component

React component to display a Marker instance.

### Usage
```javascript
import React, { FunctionComponent } from 'react';
import { APIProvider, Map, Marker } from '@vis.gl/react-google-maps';

const App: FunctionComponent<Record<string, unknown>> = () => (
  <APIProvider apiKey={'Your API key here'}>
    <Map zoom={12} center={{ lat: 53.54992, lng: 10.00678 }}>
      <Marker position={{ lat: 53.54992, lng: 10.00678 }} />
    </Map>
  </APIProvider>
);

export default App;
```

### Props
The MarkerProps interface extends the google.maps.MarkerOptions interface and includes all possible options available for a Maps JavaScript API Marker. Additionally, it is possible to add different event listeners, e.g. the click event with the `onClick` property.

```typescript
interface MarkerProps extends google.maps.MarkerOptions {
  onClick?: (e: google.maps.MapMouseEvent) => void;
  onDrag?: (e: google.maps.MapMouseEvent) => void;
  onDragStart?: (e: google.maps.MapMouseEvent) => void;
  onDragEnd?: (e: google.maps.MapMouseEvent) => void;
  onMouseOver?: (e: google.maps.MapMouseEvent) => void;
  onMouseOut?: (e: google.maps.MapMouseEvent) => void;
}
```

To see a Marker on the Map, the `position` property needs to be set.
```

--------------------------------

### Get API Loading Status

Source: https://visgl.github.io/react-google-maps/docs/api-reference/hooks/use-api-loading-status

Use this hook to access the current loading status of the Google Maps API. It's useful for handling loading errors by checking the status against `APILoadingStatus.FAILED`.

```javascript
import {useApiLoadingStatus, APILoadingStatus} from '@vis.gl/react-google-maps';  

const MyComponent = () => {  
  const status = useApiLoadingStatus();  
  
  useEffect(() => {  
    if (status === APILoadingStatus.FAILED) {  
      console.log(':(');  

      return;  
    }  
  }, [status]);  
  
  // ...  
};  
```

--------------------------------

### Render Custom Component in Map Control Container

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/map-control

Use MapControl to place any React component within the map's control containers. This example demonstrates adding a component to the top-left position.

```javascript
import {
  APIProvider,
  ControlPosition,
  Map,
  MapControl
} from '@vis.gl/react-google-maps';

const App = () => (
  <APIProvider apiKey={'...'}>
    <Map {...mapProps}>
      <MapControl position={ControlPosition.TOP_LEFT}>
        .. any component here will be added to the control-containers of the
        google map instance ..
      </MapControl>
    </Map>
  </APIProvider>
);
```

--------------------------------

### Basic Marker3D Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/marker-3d

Demonstrates the basic usage of the Marker3D component within a Map3D. Ensure APIProvider is set up with your API key.

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

const App = () => (
  <APIProvider apiKey={'Your API key here'}>
    <Map3D
      defaultCenter={{lat: 37.7749, lng: -122.4194, altitude: 500}}
      defaultRange={2000}
      defaultTilt={60}>
      <Marker3D position={{lat: 37.7749, lng: -122.4194}} />
    </Map3D>
  </APIProvider>
);
```

--------------------------------

### Accessing the Map Instance with useMap Hook

Source: https://visgl.github.io/react-google-maps/docs/guides/interacting-with-google-maps-api

Use the `useMap` hook to get access to the underlying `google.maps.Map` instance. This hook is available for any child component wrapped in `<APIProvider>`. Ensure the map instance is available before interacting with it.

```javascript
import React, {useEffect} from 'react';

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


const MyComponent = () => {
  const map = useMap();

  useEffect(() => {
    if (!map) return;

    // here you can interact with the imperative maps API

  }, [map]);

  return <></>;
};

const App = () => (
  <APIProvider apiKey={'YOUR API KEY HERE'}>
    <Map /* ... */></Map>

    <MyComponent />
  </APIProvider>
);
```

--------------------------------

### Connecting AdvancedMarker with InfoWindow using useAdvancedMarkerRef

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/advanced-marker

Shows how to use the useAdvancedMarkerRef hook to connect an AdvancedMarker with an InfoWindow. This hook provides a ref for the marker and its anchor for the InfoWindow.

```javascript
import {
  AdvancedMarker,
  InfoWindow,
  useAdvancedMarkerRef
} from '@vis.gl/react-google-maps';

const MarkerWithInfoWindow = props => {
  const [markerRef, marker] = useAdvancedMarkerRef();

  return (
    <>
      <AdvancedMarker position={props.position} ref={markerRef} />
      <InfoWindow anchor={marker}>Infowindow Content</InfoWindow>
    </>
  );
};

```

--------------------------------

### Info Window Properties

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/info-window

Configuration options for the Info Window component, including display behavior, content styling, and event handling.

```APIDOC
## Info Window Component Properties

### Description
Properties that can be passed to the InfoWindow component to customize its behavior and appearance.

### Properties
#### `disableAutoPan` (boolean)
Disable panning the map to make the InfoWindow fully visible when it opens.

#### `shouldFocus` (boolean)
Whether focus should be moved inside the InfoWindow when it is opened. It is recommended to explicitly set this property as the default heuristic is subject to change.

#### `className` (string)
A className to be assigned to the topmost element in the infowindow content.

#### `style` (CSSProperties)
A style declaration to be added to the topmost element in the infowindow content.

#### `ariaLabel` (string)
AriaLabel to assign to the InfoWindow.

#### `minWidth` (number)
Minimum width of the InfoWindow. It is strongly recommended to set this to a value less than the map's width. Cannot be changed while the InfoWindow is open.

#### `maxWidth` (number)
Maximum width of the InfoWindow.

#### `headerContent` (string | ReactNode)
The content to display in the InfoWindow header row. Can be JSX or HTML string. Requires `APIProvider` version set to `beta`.

#### `headerDisabled` (boolean)
Disables the whole header row in the InfoWindow, including the close button. Requires `APIProvider` version set to `beta`.

### Events
#### `onClose` ( () => void )
This event is fired whenever the InfoWindow closes (e.g., unmounting, escape key, close button click, anchor marker removal).

#### `onCloseClick` ( () => void )
This event is fired when the close button was clicked.
```

--------------------------------

### Basic AdvancedMarker Usage

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/advanced-marker

Demonstrates how to use the AdvancedMarker component to add a default red marker and a customized green marker to the map. Ensure the Map component has a 'mapId' specified for cloud-based styling.

```javascript
import {AdvancedMarker} from './advanced-marker';


<Map {...mapProps}>
  {/* red default marker */}
  <AdvancedMarker position={{lat: 29.5, lng: -81.2}} />
  
  {/* customized green marker */}
  <AdvancedMarker position={{lat: 29.5, lng: -81.2}}>
    <Pin  
      background={'#0f9d58'}
      borderColor={'#006425'}
      glyphColor={'#60d98f'}
    />  
  </AdvancedMarker>
  
  {/* fully customized marker */}
  <AdvancedMarker position={{lat: 29.5, lng: -81.2}>
    <img src={markerImage} width={32} height={32} />  
  </AdvancedMarker>
</Map>;
```

--------------------------------

### Uncontrolled Map Initialization

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/map

Demonstrates using default props to initialize the map's camera position and zoom level without explicit state management.

```APIDOC
## Uncontrolled Map Initialization

### Description
This example shows how to initialize the map using uncontrolled props (`defaultCenter` and `defaultZoom`). These props are only applied when the map is first rendered and do not update if changed later.

### Method
N/A (React Component)

### Endpoint
N/A (React Component)

### Parameters
#### Props
- **defaultCenter** (google.maps.LatLngLiteral) - Required - The initial latitude and longitude for the map's center on first render.
- **defaultZoom** (number) - Required - The initial zoom level for the map on first render.
```

--------------------------------

### Controlled Map3D with Camera Events

Source: https://visgl.github.io/react-google-maps/docs/api-reference/components/map-3d

Shows how to use controlled camera props (`center`, `range`, `heading`, `tilt`) and handle `cameraChanged` events to update the camera state.

```APIDOC
## Controlled Map3D with Camera Events

### Description
Shows how to use controlled camera props (`center`, `range`, `heading`, `tilt`) and handle `cameraChanged` events to update the camera state.

### Component
`<Map3D>`

### Props
- `mode` (string) - Required - The rendering mode for the map (e.g., "SATELLITE").
- `center` (object) - Optional - The current center position of the map with altitude.
  - `lat` (number) - Latitude.
  - `lng` (number) - Longitude.
  - `altitude` (number) - Altitude.
- `range` (number) - Optional - The current distance from the camera to the center of the map.
- `heading` (number) - Optional - The current compass heading of the camera.
- `tilt` (number) - Optional - The current tilt angle of the camera.
- `onCameraChanged` (function) - Optional - Callback function triggered when the camera parameters change.
  - `ev` (Map3DCameraChangedEvent) - Event object containing the new camera details.

### Example
```javascript
import {Map3DCameraChangedEvent} from '@vis.gl/react-google-maps';
import {useState, useCallback} from 'react';

const INITIAL_CAMERA = {
  center: {lat: 37.7749, lng: -122.4194, altitude: 500},
  range: 2000,
  heading: 0,
  tilt: 60
};

const ControlledMap3D = () => {
  const [center, setCenter] = useState(INITIAL_CAMERA.center);
  const [range, setRange] = useState(INITIAL_CAMERA.range);
  const [heading, setHeading] = useState(INITIAL_CAMERA.heading);
  const [tilt, setTilt] = useState(INITIAL_CAMERA.tilt);

  const handleCameraChange = useCallback((ev: Map3DCameraChangedEvent) => {
    setCenter(ev.detail.center);
    setRange(ev.detail.range);
    setHeading(ev.detail.heading);
    setTilt(ev.detail.tilt);
  }, []);

  return (
    <Map3D
      mode="SATELLITE"
      center={center}
      range={range}
      heading={heading}
      tilt={tilt}
      onCameraChanged={handleCameraChange}
    />
  );
};
```
```

--------------------------------

### Rendering a 3D Map with a Marker

Source: https://visgl.github.io/react-google-maps/docs/whats-new

Utilize `<Map3D>` and `<Marker3D>` for displaying photorealistic 3D maps and placing markers within them.

```jsx
<Map3D  
  defaultCenter={{lat: 37.7749, lng: -122.4194, altitude: 1000}}
  defaultRange={5000}
  defaultTilt={45}>
  <Marker3D position={{lat: 37.7749, lng: -122.4194, altitude: 0}} />
</Map3D>
```