googlemaps-samples · willum070 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026 · Aug 6, 2026
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -40,7 +40,7 @@
     "@vis.gl/react-google-maps": "1.8.3",
     "dotenv": "^17.4.2",
     "react": "^19.2.8",
-    "react-dom": "^19.2.7"
+    "react-dom": "^19.2.8"
   },
   "overrides": {
     "fast-xml-parser": "5.7.1",

diff --git a/samples/rgm-basic-map/README.md b/samples/rgm-basic-map/README.md
@@ -0,0 +1,62 @@
+# Google Maps JavaScript Sample
+
+## rgm-basic-map
+
+React Google Maps Library - Basic Map
+
+## Setup
+
+### Before starting run:
+
+`npm i`
+
+### Run an example on a local web server
+
+`cd samples/rgm-basic-map`
+`npm start`
+
+### Build an individual example
+
+`cd samples/rgm-basic-map`
+`npm run build`
+
+From 'samples':
+
+`npm run build --workspace=rgm-basic-map/`
+
+### Build all of the examples.
+
+From 'samples':
+
+`npm run build-all`
+
+### Run lint to check for problems
+
+`cd samples/rgm-basic-map`
+`npx eslint index.ts`
+
+## Feedback
+
+For feedback related to this sample, please open a new issue on
+[GitHub](https://github.com/googlemaps-samples/js-api-samples/issues).
+
+## Integrating React with the Google Maps JavaScript API
+
+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 via React Context.
+
+### 2. Map Component
+
+Instead of manually instantiating `new google.maps.Map()` and attaching it to a DOM node, the `<Map>` component allows you to 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 passed 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.
+
+- **Gotcha:** `AdvancedMarker` requires a valid `mapId` to be provided to the parent `<Map>` component to function correctly.
diff --git a/samples/rgm-basic-map/index.html b/samples/rgm-basic-map/index.html
@@ -0,0 +1,36 @@
+<!doctype html>
+<!--
+ @license
+ Copyright 2026 Google LLC. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+-->
+<!-- [START maps_rgm_basic_map] -->
+<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>
+<!-- [END maps_rgm_basic_map] -->
diff --git a/samples/rgm-basic-map/package.json b/samples/rgm-basic-map/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "@js-api-samples/rgm-basic-map",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "build": "bash ../build-single.sh",
+    "test": "tsc && npm run build:vite --workspace=.",
+    "start": "tsc && vite build --config ../../vite.config.js --base './' && vite --config ../../vite.config.js",
+    "build:vite": "vite build --config ../../vite.config.js --base './'",
+    "preview": "vite preview --config ../../vite.config.js"
+  },
+  "author": "Google LLC"
+}
diff --git a/samples/rgm-basic-map/src/app.tsx b/samples/rgm-basic-map/src/app.tsx
@@ -0,0 +1,38 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// [START maps_rgm_basic_map]
+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>
+    );
+}
+// [END maps_rgm_basic_map]
diff --git a/samples/rgm-basic-map/tsconfig.json b/samples/rgm-basic-map/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.react-base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["./src/**/*.ts*"]
+}