Skip to content

README.md

Latest commit

 

History

History
201 lines (143 loc) · 7.84 KB

README.md

File metadata and controls

201 lines (143 loc) · 7.84 KB

npm Release Stable Tests/Build

codecov semantic-release solidarity

Contributors License StackOverflow Discord

Google Maps JavaScript API React Wrapper

Note

Development of this package has been discontinued. We recommend all users of this package to switch to the new @vis.gl/react-google-maps, which provides a collection of components and hooks and can be configured to be fully compatible with this package.

See the migration guide for more details on how to switch from this package to @vis.gl/react-google-maps.

Description

This repository contains the React wrapper components for the Google Maps JavaScript API.

Requirements

Installation

Loading the library

Wrap React components with this library to load the Google Maps JavaScript API.

import {Wrapper} from '@googlemaps/react-wrapper';

const MyApp = () => (
  <Wrapper apiKey={'YOUR_API_KEY'}>
    <MyMapComponent />
  </Wrapper>
);

The preceding example will not render any elements unless the Google Maps JavaScript API is successfully loaded. To handle error cases and the time until load is complete, it is recommended to provide render props.

import {Wrapper, Status} from '@googlemaps/react-wrapper';

const render = status => {
  switch (status) {
    case Status.LOADING:
      return <Spinner />;
    case Status.FAILURE:
      return <ErrorComponent />;
    case Status.SUCCESS:
      return <MyMapComponent />;
  }
};

const MyApp = () => <Wrapper apiKey={'YOUR_API_KEY'} render={render} />;

When combining children and render props, the children will render on success and the render prop will be executed for other status values.

import {Wrapper, Status} from '@googlemaps/react-wrapper';

const render = (status: Status): ReactElement => {
  if (status === Status.FAILURE) return <ErrorComponent />;
  return <Spinner />;
};

const MyApp = () => (
  <Wrapper apiKey={'YOUR_API_KEY'} render={render}>
    <MyMapComponent />
  </Wrapper>
);

@googlemaps/js-api-loader

This wrapper uses @googlemaps/js-api-loader to load the Google Maps JavaScript API. This library uses a singleton pattern and will not attempt to load the library more than once. All options accepted by @googlemaps/js-api-loader are also accepted as props to the wrapper component.

MyMapComponent

The following snippets demonstrates the usage of useRef and useEffect hooks with Google Maps.

function MyMapComponent({
  center,
  zoom,
}: {
  center: google.maps.LatLngLiteral;
  zoom: number;
}) {
  const ref = useRef();

  useEffect(() => {
    new window.google.maps.Map(ref.current, {
      center,
      zoom,
    });
  });

  return <div ref={ref} id="map" />;
}

Examples

See the examples folder for additional usage patterns.

Install

Available via npm as the package @googlemaps/react-wrapper.

npm i @googlemaps/react-wrapper

or

yarn add @googlemaps/react-wrapper

For TypeScript support additionally install type definitions.

npm i -D @types/google.maps

or

yarn add -D @types/google.maps

Documentation

The reference documentation can be found at this link.

Contributing

Contributions are welcome and encouraged! If you'd like to contribute, send us a pull request and refer to our code of conduct and contributing guide.

Attribution

As a reminder, you must comply with all applicable attribution requirements for the Google Maps Platform API(s) and SDK(s) used by the Extended Component Library.

Terms of Service

This library uses Google Maps Platform services. Use of Google Maps Platform services through this library is subject to the Google Maps Platform Terms of Service.

This library is not a Google Maps Platform Core Service. Therefore, the Google Maps Platform Terms of Service (e.g. Technical Support Services, Service Level Agreements, and Deprecation Policy) do not apply to the code in this library.

Support

This library is offered via an open source license. It is not governed by the Google Maps Platform Support [Technical Support Services Guidelines, the SLA, or the Deprecation Policy. However, any Google Maps Platform services used by the library remain subject to the Google Maps Platform Terms of Service.

This library adheres to semantic versioning to indicate when backwards-incompatible changes are introduced. Accordingly, while the library is in version 0.x, backwards-incompatible changes may be introduced at any time.

If you find a bug, or have a feature request, please file an issue on GitHub. If you would like to get answers to technical questions from other Google Maps Platform developers, ask through one of our developer community channels. If you'd like to contribute, please check the contributing guide.

You can also discuss this library on our Discord server.