react-google-maps

React.js Google Maps integration component

Call for maintainers

As the author (tomchentw) currently doesn't actively use this module, he's looking for awesome contributors to help and keep the community healthy. Please don't hensitate to contact him directly. See #266 for more information.

Quick start: SimpleMap

Declare your Google Maps components using React components.

import {GoogleMapLoader, GoogleMap, Marker} from "react-google-maps";

export default function SimpleMap (props) {
  return (
    <section style={{height: "100%"}}>
      <GoogleMapLoader
        containerElement={
          <div
            {...props.containerElementProps}
            style={{
              height: "100%",
            }}
          />
        }
        googleMapElement={
          <GoogleMap
            ref={(map) => console.log(map)}
            defaultZoom={3}
            defaultCenter={{ lat: -25.363882, lng: 131.044922 }}
            onClick={props.onMapClick}
          >
            {props.markers.map((marker, index) => {
              return (
                <Marker
                  {...marker}
                  onRightclick={() => props.onMarkerRightclick(index)} />
              );
            })}
          </GoogleMap>
        }
      />
    </section>
  );
}

Documentation

Rule 1

Define <GoogleMap> component in the top level. Use containerProps, containerTagName to customize the wrapper DOM for the component.

Other components like <Marker> belong to the children of <GoogleMap>. You already know this from the example code above.

Rule 2

Everything in the Methods table in the official documentation of the component could be set directly via component's props . For example, a <Marker> component has the following props:

animation, attribution, clickable, cursor, draggable, icon, label, opacity, options, place, position, shape, title, visible, zIndex

Rule 3

Every props mentioned in Rule 2 could be either controlled or uncontrolled property. Free to use either one depends on your use case.

Rule 4

Anything that is inside components' options property can ONLY be accessible via props.options. It's your responsibility to manage the props.options object during the React lifetime of your component. My suggestion is, always use Rule 3 if possible. Only use options when it's necessary.

Rule 5

Event handlers on these components can be bound using React component convention. There's a list of event names that exist in the eventLists folder. Find the supported event name and use the form of on${ camelizedEventName }. For example, If I want to add center_changed callback to a map instance, I'll do the following with react-google-maps:

<GoogleMap
  // onCenterChanged: on + camelizedEventName(center_change)
  onCenterChanged={this.handleCenterChanged}
/>

The list of event names can be found here.

Check the examples

Static hosted demo site on GitHub. The code is located under examples/gh-pages folder.

Usage

react-google-maps requires React >= 0.14

npm install --save react-google-maps

All components are available on the top-level export.

import { GoogleMap, Marker, SearchBox } from "react-google-maps";

Loading Libraries

To use this component, you are going to need to load the Google Maps Javascript API. It is optional, but recommended, to specify the libraries you will be using as well as your API key.

You could do it synchronously like so:

<script type="text/javascript"
      src="https://maps.googleapis.com/maps/api/js?key=[YOUR_API_KEY]&libraries=geometry,places,visualization">
</script>

<GoogleMapLoader
        query={{ libraries: "geometry,drawing,places,visualization" }}
  ...

Or asynchronously using the ScriptjsLoader:

<ScriptjsLoader
  hostname={"maps.googleapis.com"}
  pathname={"/maps/api/js"}
  query={{ key: "[YOUR_API_KEY]", libraries: "geometry,drawing,places" }}
  ...

Trigger events

triggerEvent(component, ...args): One common event trigger is to resize map after the size of the container div change.

import {triggerEvent} from "react-google-maps/lib/utils";

function handleWindowResize () {
  triggerEvent(this._googleMapComponent, "resize");
}
// and you'll get `this._googleMapComponent` like this:
<GoogleMap ref={it => this._googleMapComponent = it} />

Optimize bundle size

You could of course import from individual modules to save your webpack's bundle size.

import GoogleMap from "react-google-maps/lib/GoogleMap"; // Or import {default as GoogleMap} ...

Additional Addons

Some addons component could ONLY be accessible via direct import:

import InfoBox from "react-google-maps/lib/addons/InfoBox";

Changelog

The changelog is automatically generated via conventional-changelog and can be found in project root as well as npm tarball.

Development

First, clone the project.

git clone ...

With Docker

Install docker@^1.8.2, docker-compose@^1.4.0 and optionally docker-machine@^0.4.1. Then,

docker-compose run --service-ports web

Then open http://192.168.59.103:8080.

192.168.59.103 is actually your ip from docker-machine ip.

If you change code in your local, you'll need to rebuild the image to make changes happen.

If you're previously using boot2docker, you may want to migrate to docker-machine instead.

docker-compose build

Without Docker

Install node. Then,

npm install
cd examples/gh-pages
npm install
npm start

Then open http://localhost:8080/webpack-dev-server/.

Contributing

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request