CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-react-google-maps--api

React.js Google Maps API integration with components and hooks for seamless Google Maps functionality

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

script-loading.mddocs/

Script Loading & Initialization

Script loading utilities for initializing the Google Maps JavaScript API with various configuration options, loading strategies, and error handling mechanisms.

Capabilities

LoadScript Component

Class-based component that loads the Google Maps JavaScript API via script injection with comprehensive configuration options.

/**
 * Loads Google Maps JavaScript API with script injection
 * Class-based component with lifecycle management
 */
interface LoadScriptProps extends LoadScriptUrlOptions {
  children?: React.ReactNode;
  id: string;
  nonce?: string;
  loadingElement?: React.ReactNode;
  onLoad?: () => void;
  onError?: (error: Error) => void;
  onUnmount?: () => void;
  preventGoogleFontsLoading?: boolean;
}

interface LoadScriptUrlOptions {
  googleMapsApiKey: string;
  libraries?: Libraries;
  language?: string;
  region?: string;
  version?: string;
  channel?: string;
  mapIds?: string[];
}

function LoadScript(props: LoadScriptProps): JSX.Element;

Usage Examples:

import React from 'react';
import { LoadScript, GoogleMap } from '@react-google-maps/api';

// Basic usage
function App() {
  return (
    <LoadScript
      id="script-loader"
      googleMapsApiKey="YOUR_API_KEY"
      libraries={['places', 'drawing']}
    >
      <GoogleMap
        center={{ lat: 40.7128, lng: -74.0060 }}
        zoom={10}
        mapContainerStyle={{ width: '100%', height: '400px' }}
      />
    </LoadScript>
  );
}

// With loading state and error handling
function AppWithLoading() {
  return (
    <LoadScript
      id="script-loader"
      googleMapsApiKey="YOUR_API_KEY"
      libraries={['places', 'drawing', 'geometry']}
      language="en"
      region="US"
      version="weekly"
      loadingElement={<div>Loading Maps...</div>}
      onLoad={() => console.log('Maps API loaded')}
      onError={(error) => console.error('Failed to load Maps API', error)}
    >
      <GoogleMap
        center={{ lat: 40.7128, lng: -74.0060 }}
        zoom={10}
        mapContainerStyle={{ width: '100%', height: '400px' }}
      />
    </LoadScript>
  );
}

LoadScriptNext Component

Hook-based alternative to LoadScript that uses useLoadScript internally, providing a more modern React approach.

/**
 * Hook-based alternative to LoadScript using useLoadScript internally
 * Provides modern React hooks approach to script loading
 */
interface LoadScriptNextProps extends UseLoadScriptOptions {
  loadingElement?: React.ReactElement;
  onLoad?: () => void;
  onError?: (error: Error) => void;
  onUnmount?: () => void;
  children: React.ReactElement;
}

function LoadScriptNext(props: LoadScriptNextProps): JSX.Element;

Usage Examples:

import React from 'react';
import { LoadScriptNext, GoogleMap } from '@react-google-maps/api';

function ModernApp() {
  return (
    <LoadScriptNext
      googleMapsApiKey="YOUR_API_KEY"
      libraries={['places', 'drawing']}
      loadingElement={<div>Loading...</div>}
    >
      <GoogleMap
        center={{ lat: 40.7128, lng: -74.0060 }}
        zoom={10}
        mapContainerStyle={{ width: '100%', height: '400px' }}
      />
    </LoadScriptNext>
  );
}

useLoadScript Hook

React hook for loading the Google Maps API script with built-in loading state management and error handling.

/**
 * Hook for loading Google Maps API script with state management
 * @param options - Configuration options for loading the script
 * @returns Object with loading state, error, and script URL
 */
interface UseLoadScriptOptions extends LoadScriptUrlOptions {
  id?: string;
  nonce?: string;
  preventGoogleFontsLoading?: boolean;
}

function useLoadScript(options: UseLoadScriptOptions): {
  isLoaded: boolean;
  loadError: Error | undefined;
  url: string;
};

Usage Examples:

import React from 'react';
import { useLoadScript, GoogleMap } from '@react-google-maps/api';

function HookBasedApp() {
  const { isLoaded, loadError } = useLoadScript({
    googleMapsApiKey: "YOUR_API_KEY",
    libraries: ['places', 'drawing'],
    language: 'en',
    region: 'US'
  });

  if (loadError) {
    return <div>Error loading maps</div>;
  }

  if (!isLoaded) {
    return <div>Loading maps</div>;
  }

  return (
    <GoogleMap
      center={{ lat: 40.7128, lng: -74.0060 }}
      zoom={10}
      mapContainerStyle={{ width: '100%', height: '400px' }}
    />
  );
}

// Advanced usage with conditional loading
function ConditionalMap() {
  const [shouldLoadMap, setShouldLoadMap] = React.useState(false);
  
  const { isLoaded, loadError } = useLoadScript({
    googleMapsApiKey: shouldLoadMap ? "YOUR_API_KEY" : "",
    libraries: ['places'],
    preventGoogleFontsLoading: true
  });

  return (
    <div>
      <button onClick={() => setShouldLoadMap(true)}>
        Load Map
      </button>
      
      {shouldLoadMap && isLoaded && (
        <GoogleMap
          center={{ lat: 40.7128, lng: -74.0060 }}
          zoom={10}
          mapContainerStyle={{ width: '100%', height: '400px' }}
        />
      )}
    </div>
  );
}

useJsApiLoader Hook

Alternative hook that uses @googlemaps/js-api-loader internally, providing a different approach to script loading.

/**
 * Alternative hook using @googlemaps/js-api-loader
 * Provides different loading strategy compared to useLoadScript
 * @param options - Configuration options for the JS API loader
 * @returns Object with loading state and error information
 */
function useJsApiLoader(options: UseLoadScriptOptions): {
  isLoaded: boolean;
  loadError: Error | undefined;
};

Usage Examples:

import React from 'react';
import { useJsApiLoader, GoogleMap } from '@react-google-maps/api';

function JsApiLoaderApp() {
  const { isLoaded, loadError } = useJsApiLoader({
    googleMapsApiKey: "YOUR_API_KEY",
    libraries: ['places', 'geometry'],
    version: "weekly"
  });

  if (loadError) {
    return <div>Error loading Google Maps API</div>;
  }

  if (!isLoaded) {
    return <div>Loading Google Maps API...</div>;
  }

  return (
    <GoogleMap
      center={{ lat: 40.7128, lng: -74.0060 }}
      zoom={10}
      mapContainerStyle={{ width: '100%', height: '400px' }}
    />
  );
}

Libraries Configuration

Type definition and configuration for Google Maps API libraries that can be loaded.

/**
 * Available Google Maps API libraries that can be loaded
 * Each library provides specific functionality and must be loaded before use
 */
type Libraries = Library[];

// Available library options (complete list):
type Library = 
  | 'drawing'        // Drawing Manager, overlays, and drawing tools
  | 'geometry'       // Geometry utilities (spherical, poly, encoding)
  | 'localContext'   // Local Context API for place details
  | 'places'         // Places API (autocomplete, search, details)
  | 'visualization'  // Data visualization (heatmaps, clustering)
  | string;          // Custom libraries

// Common library combinations:
const commonLibraries: Libraries = [
  'places',      // Places API for autocomplete, search
  'drawing',     // Drawing tools and shapes
  'geometry',    // Geometric utility functions
  'visualization' // Heatmap and other visualizations
];

const basicLibraries: Libraries = ['places'];
const advancedLibraries: Libraries = ['places', 'drawing', 'geometry'];
const fullLibraries: Libraries = ['places', 'drawing', 'geometry', 'visualization', 'localContext'];

Library Usage Examples:

// Load specific libraries for different features
const placesLibraries: Libraries = ['places'];
const drawingLibraries: Libraries = ['drawing', 'geometry'];
const visualizationLibraries: Libraries = ['visualization'];
const allLibraries: Libraries = ['places', 'drawing', 'geometry', 'visualization', 'localContext'];

// Use with LoadScript
<LoadScript
  googleMapsApiKey="YOUR_API_KEY"
  libraries={allLibraries}
>
  {/* Your map components */}
</LoadScript>

// Use with hooks
const { isLoaded } = useLoadScript({
  googleMapsApiKey: "YOUR_API_KEY",
  libraries: placesLibraries
});

Advanced Configuration

Advanced configuration options for script loading behavior and optimization.

/**
 * Advanced configuration options for script loading
 */
interface LoadScriptUrlOptions {
  googleMapsApiKey: string;
  libraries?: Libraries;
  language?: string;        // Language code (e.g., 'en', 'es', 'fr')
  region?: string;         // Region code (e.g., 'US', 'GB', 'DE')
  version?: string;        // API version ('weekly', 'quarterly', or specific version)
  channel?: string;        // Release channel for Google Maps Platform
  mapIds?: string[];       // Map IDs for custom styling
}

Advanced Usage Examples:

// Localized map with region-specific defaults
const { isLoaded } = useLoadScript({
  googleMapsApiKey: "YOUR_API_KEY",
  libraries: ['places'],
  language: 'es',
  region: 'ES',
  version: 'weekly'
});

// Enterprise configuration with custom map styles
const { isLoaded } = useLoadScript({
  googleMapsApiKey: "YOUR_API_KEY",
  libraries: ['places', 'drawing'],
  channel: 'enterprise',
  mapIds: ['your-custom-map-style-id'],
  version: 'quarterly'
});

// Security-focused configuration
<LoadScript
  id="secure-script-loader"
  googleMapsApiKey="YOUR_API_KEY"
  nonce="your-csp-nonce"
  preventGoogleFontsLoading={true}
  libraries={['places']}
>
  <GoogleMap />
</LoadScript>

Install with Tessl CLI

npx tessl i tessl/npm-react-google-maps--api

docs

clustering.md

core-map.md

drawing-shapes.md

index.md

layers.md

markers-overlays.md

places.md

script-loading.md

services.md

tile.json