Skip to main content

@ttoss/google-maps

@ttoss/google-maps is an opinionated way to use Google Maps in your React application.

Installing​

Install @ttoss/google-maps in your project:

$ pnpm add @ttoss/google-maps

If you use TypeScript, install the types for Google Maps:

$ pnpm add -D @types/google.maps

Then, add the following to a declaration file (generally typings.d.ts):

typings.d.ts
/// <reference types="google.maps" />

Getting Started​

Configuring GoogleMapsProvider​

At the root of your application, configure GoogleMapsProvider with your Google Maps API key. This way, the whole application can access the google variable.

import { GoogleMapsProvider } from '@ttoss/google-maps';

const App = ({ children }) => {
  return (
    <OtherProviders>
      <GoogleMapsProvider apiKey={process.env.GOOGLE_MAPS_API_KEY}>
        {children}
      </GoogleMapsProvider>
    </OtherProviders>
  );
};

Rendering the Map​

At the component level, render Google Maps using useMap hook:

import { Box, Text } from '@ttoss/ui';
import { useMap } from '@ttoss/google-maps';

const MyComponent = () => {
  const { ref, map } = useMap();

  React.useEffect(() => {
    if (map) {
      map.setOptions({
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
      });
    }
  }, [map]);

  return (
    <Box>
      <Text>My Map</Text>
      <Box ref={ref} sx={{ height, width }} />
    </Box>
  );
};

If everything is set up correctly, you should see a map centered at the specified coordinates.

Retrieve google.maps object​

If you need to access the google.maps object, you can use the useGoogleMaps hook:

import { useGoogleMaps } from '@ttoss/google-maps';

const MyComponent = () => {
  const { google } = useGoogleMaps();

  return <Text>{google.maps.version}</Text>;
};

With this, you can perform any operation that the google.maps object allows, such as creating markers, drawing polygons, etc.

Advanced Usage​

Using with Next.js (custom Script component)​

If you use Next.js, you can use the GoogleMapsProvider passing Next.js Script component as a prop:

import { GoogleMapsProvider } from '@ttoss/google-maps';
import Script from 'next/script';

const App = ({ children }) => {
  return (
    <OtherProviders>
      <GoogleMapsProvider
        apiKey={process.env.GOOGLE_MAPS_API_KEY}
        Script={Script}
      >
        {children}
      </GoogleMapsProvider>
    </OtherProviders>
  );
};

Reusing map object​

If you need to access the map object in multiple components, you can use MapProvider to share it:

import { MapProvider, useMap } from '@ttoss/google-maps';

const ChildComponent = () => {
  // Access the map object created by the parent component
  const { map } = useMap();

  React.useEffect(() => {
    if (map) {
      map.setOptions({
        center: { lat: -34.397, lng: 150.644 },
        zoom: 8,
      });
    }
  }, [map]);

  return null;
};

const ParentComponent = () => {
  const { ref, map } = useMap();

  return (
    <MapProvider map={map} ref={ref}>
      <Box>
        <Text>My Map</Text>
        <Box ref={ref} sx={{ height, width }} />
        <ChildComponent />
      </Box>
    </MapProvider>
  );
};

API​

GoogleMapsProvider​

Props​

  • apiKey: string - Google Maps API key.
  • libraries: string[] - Libraries to load.
  • language: string - Language.
  • Script: React.ComponentType - Custom Script component to use.
  • onError: (error: Error) => void - Callback to handle script loading errors.

MapProvider​

Props​

  • map: google.maps.Map | null - Google Maps object.
  • children: React.ReactNode - Children to render.
  • ref: React.RefObject<HTMLDivElement> - Reference to the map container.

useMap​

useMap is a hook that returns a reference to the map container and the Google Maps object. It creates a new map object if it doesn't exist or returns the existing map if MapProvider wraps the component tree.

Returns​

  • ref: React.RefObject<HTMLDivElement> - Reference to the map container.
  • map: google.maps.Map | null - Google Maps object.

useGoogleMaps​

Returns​

  • google: typeof google - google.maps object.
  • status: 'idle' | 'error' | 'loading' | 'ready' - Status of the script loading.
  • isReady: boolean - Whether the script is ready. The same as status === 'ready'.