This example uses the
[vis.gl/react-google-maps](https://visgl.github.io/react-google-maps/) open
source library to render a Google map in a React app. The
[vis.gl/react-google-maps](https://visgl.github.io/react-google-maps/) library
is a collection of React components and hooks for the Google Maps JavaScript
API.

> [!IMPORTANT]
> **Important:** The [vis.gl/react-google-maps](https://visgl.github.io/react-google-maps/) library is offered using an open source license. It is not governed by the Google Maps Platform Support Technical Support Services Guidelines, the SLA, or the Deprecation Policy (however, any Google Maps Platform services used by the library remain subject to the Google Maps Platform Terms of Service). If you find a bug, or have a feature request, file an issue on [GitHub](https://github.com/visgl/react-google-maps/issues) .

<iframe src="https://maps-docs-team.web.app/samples/rgm-basic-map/dist/" allow="fullscreen; "></iframe>

### TypeScript

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

const API_KEY = 'GOOGLE_MAPS_API_KEY';

export default function App() {
    return (
        <APIProvider apiKey={API_KEY}>
            <Map
                defaultCenter={{ lat: 37.4220656, lng: -122.0840897 }}
                defaultZoom={10}
                mapId="DEMO_MAP_ID">
                <AdvancedMarker
                    position={{ lat: 37.4220656, lng: -122.0840897 }}
                    title="Mountain View, CA"
                />
            </Map>
        </APIProvider>
    );
}

export function renderToDom(container: HTMLElement) {
    const root = createRoot(container);
    root.render(
        <React.StrictMode>
            <App />
        </React.StrictMode>
    );
}
```

### JavaScript

```javascript
import React from 'react';
import { createRoot } from 'react-dom/client';
import { APIProvider, Map, AdvancedMarker } from '@vis.gl/react-google-maps';
const API_KEY = 'GOOGLE_MAPS_API_KEY';
export default function App() {
    return (React.createElement(APIProvider, { apiKey: API_KEY },
        React.createElement(Map, { defaultCenter: { lat: 37.4220656, lng: -122.0840897 }, defaultZoom: 10, mapId: "DEMO_MAP_ID" },
            React.createElement(AdvancedMarker, { position: { lat: 37.4220656, lng: -122.0840897 }, title: "Mountain View, CA" }))));
}
export function renderToDom(container) {
    const root = createRoot(container);
    root.render(React.createElement(React.StrictMode, null,
        React.createElement(App, null)));
}
```

### HTML

```html
<html lang="en">
    <head>
        <meta charset="utf-8" />
        <meta
            name="viewport"
            content="width=device-width, initial-scale=1.0, user-scalable=no" />
        <title>React - Basic Map</title>
        <meta name="description" content="React Basic Map Example" />
        <style>
            body {
                margin: 0;
                font-family: sans-serif;
            }
            #app {
                width: 100vw;
                height: 100vh;
            }
        </style>
        <script type="module">
            import { renderToDom } from './src/app';

            renderToDom(document.querySelector('#app'));
        </script>
    </head>
    <body>
        <div id="app"></div>
    </body>
</html>
```

### Clone Sample


Git and Node.js are required to run this sample locally. Follow these [instructions](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)
to install Node.js and NPM. You will also need a [Google Maps API key](https://developers.google.com/maps/documentation/javascript/get-api-key.md.txt).


The following commands clone the repository, install dependencies, and copy the environment file.

```javascript
  git clone https://github.com/googlemaps-samples/js-api-samples.git
  cd js-api-samples
  npm i
  cp .env.template .env
```


Once you copy the environment file, make sure to open the `.env` file and replace `<Insert your own development API key here>` with your actual API key before starting the sample.

```javascript
  cd samples/rgm-basic-map
  npm start
```

## Integration notes

When integrating Google Maps within a React application, this sample implements
several key best practices using the open source `@vis.gl/react-google-maps`
library.

### 1. APIProvider

The `<APIProvider>` component is used at the root of the application to
load the Google Maps JavaScript API script once. It handles the API loading
state and makes the Google Maps instance available to all child components using
React Context.

### 2. Map Component

Instead of manually instantiating `new google.maps.Map()` and attaching it
to a DOM node, the `<Map>` component lets you define the map
declaratively.

- By using `defaultCenter` and `defaultZoom`, we create an "uncontrolled" map component where the map manages its own state internally, while still initializing it to the correct location.
- The `mapId` property is required to enable Cloud-based Maps Styling and Advanced Markers.

### 3. Advanced Markers

The legacy `google.maps.Marker` class is deprecated. This sample uses the
`<AdvancedMarker>` component to declaratively render the modern
`AdvancedMarkerElement` directly on the map.

### 4. TypeScript types

If your components reference the `google.maps` namespace, install the
`@types/google.maps` package to get access to the full range of Google Maps
TypeScript types. If your `tsconfig` file sets the `types` compiler option,
also add `google.maps` to the `types` array. For details, see
[TypeScript and Google Maps](https://developers.google.com/maps/documentation/javascript/using-typescript.md.txt#tsconfig_types).