visgl · anglarett · May 21, 2026 · May 21, 2026 · May 21, 2026
diff --git a/.gitignore b/.gitignore
@@ -1,5 +1,6 @@
 /node_modules
 /dist
+/.env*
 /examples/**/package-lock.json
 /examples/**/node_modules
 /examples/**/dist

diff --git a/examples/map-3d-routes-widget/README.md b/examples/map-3d-routes-widget/README.md
@@ -0,0 +1,38 @@
+# 3D Map Route Example
+
+This is a standalone example demonstrating how to render a client-side 3D route using the modern `<gmp-route-3d>` custom element inside a client-side 3D Map (`<Map3D>`).
+
+It showcases the seamless integration of the Maps JS API routes and maps3d libraries in React.
+
+## Google Maps Platform API Key & Requirements
+
+To run this example locally, you must satisfy the following platform requirements:
+
+1. **Billing Enabled:** The Routes API and 3D Maps are premium Google Maps features and require a Google Cloud project with an **active billing account** linked to it.
+2. **Enabled APIs & Alpha Channel:** Ensure that both the **Routes API** and the **Maps JavaScript API** are explicitly enabled in your Google Cloud Console. **Note:** The `<gmp-route-3d>` custom element is currently only available in the **Alpha channel** (e.g., by setting `version="alpha"` on your `<APIProvider>`).
+3. **API Key Environment Variable:** The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+## WebGL2 Browser Compatibility
+
+Photorealistic 3D Maps require WebGL2 support and hardware graphics acceleration. Please refer to the official **[Google Maps 3D Maps Browser Support Guide](https://developers.google.com/maps/documentation/javascript/3d-maps-support)** for detailed browser requirements and system compatibility guidelines.
+
+_(Note: Virtual machine or remote desktop environments like Cloudtop do not support direct WebGL2 hardware rendering overlays by default. Please run the example locally on your physical host machine)._
+
+## Development & How to Run
+
+Go into the example directory:
+
+```shell
+cd examples/map-3d-route
+```
+
+Install dependencies and start the development server:
+
+```shell
+npm install
+npm run start-local
+```
diff --git a/examples/map-3d-routes-widget/index.html b/examples/map-3d-routes-widget/index.html
@@ -0,0 +1,32 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no" />
+    <title>Example: 3D Map Route</title>
+
+    <style>
+      body {
+        font-size: 16px;
+        margin: 0;
+        font-family: sans-serif;
+      }
+      #app {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module">
+      import '@vis.gl/react-google-maps/examples.css';
+      import '@vis.gl/react-google-maps/examples.js';
+      import {renderToDom} from './src/app';
+
+      renderToDom(document.querySelector('#app'));
+    </script>
+  </body>
+</html>
diff --git a/examples/map-3d-routes-widget/package.json b/examples/map-3d-routes-widget/package.json
@@ -0,0 +1,18 @@
+{
+  "type": "module",
+  "dependencies": {
+    "@googlemaps/js-api-loader": "^2.0.2",
+    "@vis.gl/react-google-maps": "latest",
+    "fast-deep-equal": "^3.1.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^6.0.3",
+    "vite": "^5.4.11"
+  },
+  "scripts": {
+    "start": "vite",
+    "start-local": "vite --config ../vite.config.local.js",
+    "build-local": "vite build --config ../vite.config.local.js",
+    "build": "vite build"
+  }
+}
diff --git a/examples/map-3d-routes-widget/src/app.css b/examples/map-3d-routes-widget/src/app.css
@@ -0,0 +1,10 @@
+/* Styles for 3D Map Route Example */
+html,
+body,
+#app {
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  overflow: hidden;
+}
diff --git a/examples/map-3d-routes-widget/src/app.tsx b/examples/map-3d-routes-widget/src/app.tsx
@@ -0,0 +1,74 @@
+import React from 'react';
+import {createRoot} from 'react-dom/client';
+
+import {APIProvider, Map3D, useMapsLibrary} from '@vis.gl/react-google-maps';
+import ControlPanel from './control-panel';
+
+import './app.css';
+
+const API_KEY =
+  globalThis.GOOGLE_MAPS_API_KEY ?? (process.env.GOOGLE_MAPS_API_KEY as string);
+
+// Tell TypeScript to allow the custom <gmp-route-3d> element
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      'gmp-route-3d': React.DetailedHTMLProps<
+        React.HTMLAttributes<HTMLElement>,
+        HTMLElement
+      > & {
+        'autofits-camera'?: boolean;
+        'departure-time'?: string;
+        destination?: any;
+        origin?: any;
+        'routing-preference'?: string;
+        'travel-mode'?: string;
+      };
+    }
+  }
+}
+
+const Map3DRouteExample = () => {
+  // Make sure routes and maps3d libraries are loaded to register the custom elements
+  useMapsLibrary('routes');
+  useMapsLibrary('maps3d');
+
+  return (
+    <>
+      <Map3D
+        defaultCenter={{lat: 43.67, lng: -79.4, altitude: 100}}
+        defaultRange={12000}
+        defaultHeading={0}
+        defaultTilt={60}
+        defaultRoll={0}
+        defaultLabelsDisabled
+        style={{width: '100vw', height: '100vh'}}>
+        <gmp-route-3d
+          origin={{lat: 43.65, lng: -79.38}}
+          destination={{lat: 43.69, lng: -79.42}}
+          travel-mode="DRIVING"
+        />
+      </Map3D>
+    </>
+  );
+};
+
+const App = () => {
+  return (
+    <APIProvider apiKey={API_KEY} version="alpha">
+      <Map3DRouteExample />
+      <ControlPanel />
+    </APIProvider>
+  );
+};
+export default App;
+
+export function renderToDom(container: HTMLElement) {
+  const root = createRoot(container);
+
+  root.render(
+    <React.StrictMode>
+      <App />
+    </React.StrictMode>
+  );
+}
diff --git a/examples/map-3d-routes-widget/src/control-panel.css b/examples/map-3d-routes-widget/src/control-panel.css
@@ -0,0 +1,42 @@
+.control-panel {
+  position: absolute;
+  top: 20px;
+  right: 20px;
+  background: rgba(255, 255, 255, 0.95);
+  padding: 15px;
+  border-radius: 8px;
+  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
+  max-width: 300px;
+  z-index: 10;
+  font-family: sans-serif;
+}
+
+.control-panel h3 {
+  margin-top: 0;
+  margin-bottom: 8px;
+  font-size: 16px;
+}
+
+.control-panel p {
+  font-size: 12px;
+  margin: 0 0 10px 0;
+  color: #4a5568;
+}
+
+.control-panel p.note {
+  font-size: 11px;
+  background: #edf2f7;
+  padding: 6px;
+  border-radius: 4px;
+}
+
+.control-panel .links a {
+  font-size: 12px;
+  color: #3182ce;
+  text-decoration: none;
+}
+
+.control-panel p.note a {
+  color: #3182ce;
+  text-decoration: underline;
+}
diff --git a/examples/map-3d-routes-widget/src/control-panel.tsx b/examples/map-3d-routes-widget/src/control-panel.tsx
@@ -0,0 +1,41 @@
+import * as React from 'react';
+import './control-panel.css';
+
+function ControlPanel() {
+  return (
+    <div className="control-panel">
+      <h3>3D Map Routes</h3>
+      <p>
+        This example demonstrates how to render a client-side 3D route using the
+        modern <code>&lt;gmp-route-3d&gt;</code> custom element inside a 3D Map.
+      </p>
+
+      <p className={'note'}>
+        <strong>Note:</strong> This utilizes custom 3D elements from the Maps JS
+        API{' '}
+        <a
+          href="https://developers.google.com/maps/documentation/javascript/reference/routes-elements"
+          target="_new">
+          routes
+        </a>{' '}
+        and{' '}
+        <a
+          href="https://developers.google.com/maps/documentation/javascript/reference/3d-map"
+          target="_new">
+          maps3d
+        </a>{' '}
+        libraries.
+      </p>
+
+      <div className="links">
+        <a
+          href="https://github.com/visgl/react-google-maps/tree/main/examples/map-3d-route"
+          target="_new">
+          View Code ↗
+        </a>
+      </div>
+    </div>
+  );
+}
+
+export default React.memo(ControlPanel);
diff --git a/examples/map-3d-routes-widget/tsconfig.json b/examples/map-3d-routes-widget/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.base.json",
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "website-examples/*": ["../*"]
+    }
+  }
+}
diff --git a/examples/map-3d-routes-widget/vite.config.js b/examples/map-3d-routes-widget/vite.config.js
@@ -0,0 +1,30 @@
+import {defineConfig, loadEnv} from 'vite';
+import {resolve} from 'node:path';
+
+export default defineConfig(({mode}) => {
+  const {GOOGLE_MAPS_API_KEY = ''} = loadEnv(mode, resolve('../../'), '');
+
+  return {
+    envDir: '../../',
+    define: {
+      'process.env.GOOGLE_MAPS_API_KEY': JSON.stringify(GOOGLE_MAPS_API_KEY)
+    },
+    resolve: {
+      alias: {
+        '@vis.gl/react-google-maps/examples.js': resolve(
+          '../../website/static/scripts/examples.js'
+        ),
+        '@vis.gl/react-google-maps/examples.css': resolve(
+          '../../examples/examples.css'
+        ),
+        '@vis.gl/react-google-maps': resolve('../../src/index.ts'),
+        '@googlemaps/js-api-loader': resolve(
+          './node_modules/@googlemaps/js-api-loader'
+        ),
+        'fast-deep-equal': resolve('./node_modules/fast-deep-equal'),
+        react: resolve('./node_modules/react'),
+        'react-dom': resolve('./node_modules/react-dom')
+      }
+    }
+  };
+});
diff --git a/examples/map-3d-routes/README.md b/examples/map-3d-routes/README.md
@@ -0,0 +1,38 @@
+# 3D Map Routes Example (JS API Programmatic)
+
+This example shows how to programmatically retrieve route details using the modern `google.maps.routes.Route.computeRoutes(...)` method and render a thinned 3D polyline overlay dynamically on a photorealistic 3D Map (`<Map3D>`).
+
+It showcases full visual control and thinned styling of polylines using the client-side Javascript SDK.
+
+## Google Maps Platform API Key & Requirements
+
+To run this example locally, you must satisfy the following platform requirements:
+
+1. **Billing Enabled:** The Routes API and 3D Maps are premium Google Maps features and require a Google Cloud project with an **active billing account** linked to it.
+2. **Enabled APIs & Alpha Channel:** Ensure that both the **Routes API** and the **Maps JavaScript API** are explicitly enabled in your Google Cloud Console. **Note:** 3D Maps and elements are currently only available in the **Alpha channel** (e.g., by setting `version="alpha"` on your `<APIProvider>`).
+3. **API Key Environment Variable:** The API key has to be provided via an environment variable `GOOGLE_MAPS_API_KEY`. This can be done by creating a file named `.env` in the example directory with the following content:
+
+```shell title=".env"
+GOOGLE_MAPS_API_KEY="<YOUR API KEY HERE>"
+```
+
+## Browser Compatibility
+
+Photorealistic 3D Maps require WebGL2 support and hardware graphics acceleration. Please refer to the official **[Google Maps 3D Maps Browser Support Guide](https://developers.google.com/maps/documentation/javascript/3d-maps-support)** for detailed browser requirements and system compatibility guidelines.
+
+_(Note: Virtual machine or remote desktop environments like Cloudtop do not support direct WebGL2 hardware rendering overlays by default. Please run the example locally on your physical host machine)._
+
+## Development & How to Run
+
+Go into the example directory:
+
+```shell
+cd examples/map-3d-routes
+```
+
+Install dependencies and start the development server:
+
+```shell
+npm install
+npm run start-local
+```
diff --git a/examples/map-3d-routes/index.html b/examples/map-3d-routes/index.html
@@ -0,0 +1,31 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta
+      name="viewport"
+      content="width=device-width, initial-scale=1.0, user-scalable=no" />
+    <title>Example: Routes API Rendering</title>
+
+    <style>
+      body {
+        margin: 0;
+        font-family: sans-serif;
+      }
+      #app {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module">
+      import '@vis.gl/react-google-maps/examples.css';
+      import '@vis.gl/react-google-maps/examples.js';
+      import {renderToDom} from './src/app';
+
+      renderToDom(document.querySelector('#app'));
+    </script>
+  </body>
+</html>