---
title: Google Maps
description: Render Google Maps only after consent with one shared Maps
  JavaScript API loader and independently managed map instances.
icon: google-maps
group: integrations
lastModified: "2026-08-04T19:55:26+01:00"
---
`GoogleMap` is a renderable integration for React and Next.js. It keeps the
Google Maps JavaScript API off the page until the configured consent category is
allowed, then loads the SDK once and creates a map for each mounted component.

Unlike the helpers from `@c15t/scripts`, `GoogleMap` owns both the consent-aware
script lifecycle and the visible map container.

> ℹ️ **Info:**
> The browser must receive a Google Maps API key, so the key is visible to site visitors. Keep it out of source control, use a key created for browser use, and restrict it by website and API in Google Cloud.

## Integrate with c15t

`GoogleMap` must render inside a `ConsentManagerProvider`. Complete the
[React quickstart](/docs/frameworks/react/quickstart) or
[Next.js quickstart](/docs/frameworks/next/quickstart) first.

**React**

```tsx
import { GoogleMap } from '@c15t/react';

const apiKey = import.meta.env.VITE_GOOGLE_MAPS_API_KEY;

export function StoreMap() {
  if (!apiKey) {
    return <p>Google Maps is not configured.</p>;
  }

  return (
    <GoogleMap
      apiKey={apiKey}
      authReferrerPolicy="origin"
      center={{ lat: 40.7128, lng: -74.006 }}
      consentCategory="measurement"
      style={{ height: 400 }}
      zoom={12}
    />
  );
}
```

**Next.js**

```tsx
'use client';

import { GoogleMap } from '@c15t/nextjs';

const apiKey = process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY;

export function StoreMap() {
  if (!apiKey) {
    return <p>Google Maps is not configured.</p>;
  }

  return (
    <GoogleMap
      apiKey={apiKey}
      authReferrerPolicy="origin"
      center={{ lat: 40.7128, lng: -74.006 }}
      consentCategory="measurement"
      style={{ height: 400 }}
      zoom={12}
    />
  );
}
```

`measurement` is a common choice for an interactive map, but the correct
category depends on why your application uses Google Maps and the policy shown
to your users.

## How c15t loads it

* **Before consent:** no Maps JavaScript API script is requested and no map
  instance is created.
* **After consent:** c15t registers one shared SDK loader and waits for Google's
  callback before constructing the map.
* **Multiple maps:** components with the same `scriptId` reuse the SDK while
  keeping separate map instances.
* **On revocation or unmount:** the component clears the map instance and its
  listeners. The page-level SDK registration is retained after its first load
  because Google supports one loader per page.
* **Existing SDK:** if another part of the application already loaded a
  compatible Google Maps global, the component adopts it instead of adding a
  duplicate script.
* **Visible states:** the blocked, loading, and error states are accessible and
  use the active c15t translations by default.

Keep one `scriptId` and one loader configuration across the page. Override the
default `scriptId` only to coordinate with a known c15t script registration, not
to load a second Maps SDK configuration. If two maps register conflicting
loader options, c15t reports the conflict and tells you to align the key,
language, region, libraries, and other loader options. A different `scriptId`
does not make a second Google loader safe.

## Configure the map

Pass `center`, `zoom`, `mapId`, and `options` as you would when constructing a
Google map:

```tsx
<GoogleMap
  apiKey={apiKey}
  center={{ lat: 51.5072, lng: -0.1276 }}
  consentCategory="measurement"
  mapId="YOUR_MAP_ID"
  options={{
    disableDefaultUI: true,
    gestureHandling: 'cooperative',
  }}
  zoom={11}
/>
```

Changes to `center`, `zoom`, and updateable `options` are applied to the existing
map. Changing `mapId` recreates it because Google treats that value as
construction-time configuration.

The component has a default height of `320px`. Override `style.height` or apply
a class with an explicit height when your layout needs another size.

### Loader options

The direct Maps JavaScript API loader options are available as component props:

* `libraries`
* `language`
* `region`
* `version`
* `authReferrerPolicy`
* `mapIds`
* `channel`
* `solutionChannel`
* `nonce`

`mapIds` preloads map ID configuration; `mapId` selects the map ID for the
component instance.

## Handle loading and errors

The built-in loading and error states use `frame.loading` and `frame.error` from
your c15t messages. The consent placeholder uses the localized consent-type
title in both its message and button—for example, an `Analytics` title produces
“Enable Analytics consent.”

Use the fallback props when you need integration-specific content and `onError`
for reporting:

```tsx
import { Frame, GoogleMap } from '@c15t/react';

function reportMapError(error: Error) {
  // Send the error to your observability provider.
}

<GoogleMap
  apiKey={apiKey}
  center={{ lat: 40.7128, lng: -74.006 }}
  consentCategory="measurement"
  loadingFallback={<p>Loading map…</p>}
  errorFallback={<p>The map could not be loaded.</p>}
  onError={reportMapError}
  placeholder={
    <Frame.Root>
      <Frame.Title>Allow measurement consent to view this map.</Frame.Title>
      <Frame.Button category="measurement" />
    </Frame.Root>
  }
/>
```

`onError` covers loader failures, timeouts, map-constructor failures, and
Google's global authentication failure callback. Authentication failures
usually indicate an invalid key, missing billing, a disabled API, or a referrer
that is not allowed.

If you provide a custom `placeholder`, include `Frame.Button` or another way to
reopen consent preferences or grant the required category.

### Retry a failed map

Increment `retryKey` to retry the same map after a loader, authentication, or
constructor failure:

```tsx
import { GoogleMap } from '@c15t/react';
import { useState } from 'react';

function RetryableMap({ apiKey }: { apiKey: string }) {
  const [retryKey, setRetryKey] = useState(0);

  return (
    <>
      <GoogleMap
        apiKey={apiKey}
        center={{ lat: 40.7128, lng: -74.006 }}
        retryKey={retryKey}
      />

      <button type="button" onClick={() => setRetryKey((key) => key + 1)}>
        Retry map
      </button>
    </>
  );
}
```

Changing `retryKey` clears the failed attempt and retries with the same
`scriptId`. A successful page-level SDK registration remains shared and is not
loaded again.

## Secure the browser key

For production:

1. Create a key specifically for the browser application.
2. Apply a **Websites** application restriction for every allowed development
   and production origin.
3. Restrict the key to the **Maps JavaScript API** and any additional APIs used
   by requested libraries.
4. Keep the value in an untracked environment file and expose it through the
   browser environment variable required by your framework.
5. Monitor key usage and rotate the key if you see unexpected traffic.

When `authReferrerPolicy="origin"` is set, configure origin-level website
restrictions without URL paths.

* [Google Maps Platform security guidance](https://developers.google.com/maps/api-security-best-practices)
* [Maps JavaScript API loader options](https://developers.google.com/maps/documentation/javascript/load-maps-js-api)
* [Maps Demo Key for local prototypes](https://developers.google.com/maps/documentation/javascript/demo-key)

## Verify setup

1. Clear saved consent and reload the page.
2. Confirm no request to `maps.googleapis.com/maps/api/js` occurs before the
   configured category is allowed.
3. Grant consent and confirm the map reaches its ready state.
4. Render two maps with the same `scriptId` and confirm only one loader script is
   added.
5. Revoke consent and confirm each map instance is removed.
6. Test a rejected key or referrer and confirm `errorFallback` and `onError`
   receive the failure.
7. Fix the rejected configuration, change `retryKey`, and confirm the map can
   recover without changing `scriptId`.

## Types

### GoogleMapProps

|Property|Value|
|:--|:--|
|Type Name|\`GoogleMapProps\`|
|Source Path|\`./packages/react/src/components/integrations/google-map.tsx\`|

\*ExtractedTypeTable: Could not extract "GoogleMapProps" from "./packages/react/src/components/integrations/google-map.tsx" using base path "/vercel/path0/apps/c15t-docs/.leadtype/c15t". Verify the path/name and that the file is included by your tsconfig.\*