Renderable

Google Maps

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 or Next.js quickstart first.

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}
    />
  );
}

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:

<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:

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:

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.

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

Warning: 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.

Loading…