React-geoinput NPM

react-geoinput

Redux-form compatible geolocation suggestions and coordinates with Google Maps API.

Features

Suggestion of locations with Google Maps API
Address geocoding with Google Maps API
Customizable debounced input
Customizable suggestion serialization and rendering
Customizable geo destination serialization and rendering
Standard input interface (compatible with redux-form)

Install

add react-geoinput as dependency

npm install --save react-geoinput

include Google Maps API

Make window.google.maps available e.g. with:

<script src="https://maps.googleapis.com/maps/api/js?libraries=places&key=YOUR_API_KEY_HERE"></script>

link: Google Maps JavaScript API / get API key

Try demos locally

$ git clone https://github.com/woltapp/react-geoinput.git
$ cd react-geoinput
$ yarn
$ yarn start

1_quickstart demonstrates the use of DefaultGeoInput
2_barebones uses only createGeoInput and demonstrates how to use the API to create your own input

What problem does the library solve?

React-geoinput makes it a breeze to combine both geolocation suggestion and geocoding an address. Generally other libraries do only either at once. A good use case for this library is to be able to turn an address into coordinates and verify that the interpreted address was correct in textual format. Moreover, this library allows complete customization of the UI, and only provides components to get you quickly started!

Examples

Quick start

import React, { Component } from 'react';
import { createGeoInput, DefaultGeoInput } from 'react-geoinput';

const SimpleInput = createGeoInput(DefaultGeoInput);

class Example extends Component {
  state = {
    address: '',
    geoDestination: '',
  }

  onAddressChange = value => this.setState({ address: value })
  onGeoDestinationChange = value => this.setState({ geoDestination: value })

  render() {
    return (
      <div>
        <SimpleInput
          addressInput={{
            onChange: this.onAddressChange,
            value: this.state.address,
          }}
          geoDestinationInput={{
            onChange: this.onGeoDestinationChange,
            value: this.state.geoDestination,
          }}
        />
      </div>
    );
  }
}

Usage with Redux-form

import React from 'react';
import { Fields } from 'redux-form';
import { createGeoInput, DefaultGeoInput } from 'react-geoinput';

const GeoInput = createGeoInput(DefaultGeoInput);

const GeoField = fields => (
  <GeoInput
    addressInput={fields.address.input}
    geoDestinationInput={fields.destination.input}
  />
);

Use with redux-form's Fields component:

<Fields names={['address', 'destination']} component={GeoField} />

API Documentation

Overview

React-geoinput exposes one higher order component (createGeoInput) and three regular stateless React components (DefaultGeoInput, GeoAddressInput, PredictiveInput).

createGeoInput contains the main logic to handle fetching location suggestions from the Google Maps API and to geocode the typed address to a location object, which includes e.g. coordinates and parsed location fields. In fact, createGeoInput provides two inputs simultaneously: typed address and geocoded location. Generally you'll want to store the information separately, since address is the arbitrary string typed by user and location is the accurate exact geolocation.

DefaultGeoInput exists to get you quickly started with the library. It contains opinionated styles and structure, which is a good starting point. If it works for you, you can customize it via the props, otherwise you can use it simply as a starting point to create your own completely custom input component. DefaultGeoInput uses GeoAddressInput underneath to provide the bare-bones input with predictions (=suggestions).

GeoAddressInput is provided as a convenience component, which simply maps the predictions (suggestions) from createGeoInput() to PredictiveInput.

PredictiveInput is provided as a utility component to provide a simple input field with predictions -- it is not coupled to geocoding or locations anyhow. It should be applicable for most cases and supports styling via props. PredictiveInput uses DebounceInput from react-debounce-input to reduce the amount of requests made to the Google Maps API.

`createGeoInput(input: Component, <options: Object>)`

createGeoInput is a higher order component that takes two arguments, first of which is your custom input (or DefaultGeoInput), and the second one is options object. It can be wrapped with a custom input component, such as with the provided DefaultGeoInput. The beef of this library's logic is in this HoC; thus you are encouraged to make a custom implementation of the input.

The following options can be set:

serializePrediction (Function): A function that takes prediction object from the Google Maps API as an argument and turns it into a string that is suggested. The structure of the prediction object is not included in this documentation.
serializeGeoDestination (Function): A function that takes geoDestination object from the Google Maps API as an argument and turns it to another object. By default it maps the geoDestination keys as following: route->street, street_number->streetNumber, subpremise->subpremise, locality->city, country->country, postal_code->postalCode, { geometry }->{ lat, lng},viewport. The structure of the geoDestination object is not included in this documentation.

Note: you won't need to change these options unless you know you are missing an important value from the Google Maps API.

`DefaultGeoInput`

DefaultGeoInput displays an input for typing the address. Predictions (=suggestions) will be shown for the address with PredictiveInput. On predicted address selection the geoDestionation will be also rendered.

Note: a good way to get started with your completely custom input is to copy the implementation of DefaultGeoInput and modify it.

Props

activeIndex (number): control the selected index of location suggestion
addressInput (object.isRequired): input controls, such as onChange, value
className (string)
geoDestinationInput (object.isRequired): input controls, such as onChange, value
geoDestinationClassName (string)
geoDestinationTableClassName (string)
loadingElement (node): element to display while loading geo destination
loadingGeoDestination (bool): control when to show loadingElement
onPredictionClick (func.isRequired): handle suggestion click, takes prediction index
predictions (array.isRequired): array of predictions from Google Maps API
style (object)

`GeoAddressInput`

Props

activeIndex (number): control the selected index of location suggestion
className (string)
onPredictionClick (func.isRequired): handles prediction click, takes prediction index
onChange (func.isRequired): handle for address input change
predictions (array.isRequired): array of predictions from Google Maps API
style (object)

`PredictiveInput`

Props

className (string)
containerClassName (string):
containerStyle (object):
debounceTimeout (number): time for debounce in ms
activePredictionId (string|number): control active prediction
predictions (arrayOf(predictionPropType)): array of predictions (see below)
predictionsClassName (string)
predictionItemClassName (string)

predictionPropType = PropTypes.shape({
  id: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
  label: PropTypes.node,
  onClick: PropTypes.func,
})