We are looking for maintainers!

In order to ensure active development going forward, we are looking for maintainers to join the project. Please contact the project owner if you are interested.

React Places Autocomplete

A React component to build a customized UI for Google Maps Places Autocomplete

Demo

Live demo: hibiken.github.io/react-places-autocomplete/

Features

1. Enable you to easily build a customized autocomplete dropdown powered by Google Maps Places Library
2. Utility functions to geocode and get latitude and longitude using Google Maps Geocoder API
3. Full control over rendering to integrate well with other libraries (e.g. Redux-Form)
4. Mobile friendly UX
5. WAI-ARIA compliant
6. Support Asynchronous Google script loading

Installation

To install the stable version

npm install --save react-places-autocomplete

React component is exported as a default export

import PlacesAutocomplete from 'react-places-autocomplete';

utility functions are named exports

import {
  geocodeByAddress,
  geocodeByPlaceId,
  getLatLng,
} from 'react-places-autocomplete';

Getting Started

<a name="load-google-library"></a> To use this component, you are going to need to load Google Maps JavaScript API

Load the library in your project

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

Create your component

import React from 'react';
import PlacesAutocomplete, {
  geocodeByAddress,
  getLatLng,
} from 'react-places-autocomplete';

class LocationSearchInput extends React.Component {
  constructor(props) {
    super(props);
    this.state = { address: '' };
  }

  handleChange = address => {
    this.setState({ address });
  };

  handleSelect = address => {
    geocodeByAddress(address)
      .then(results => getLatLng(results[0]))
      .then(latLng => console.log('Success', latLng))
      .catch(error => console.error('Error', error));
  };

  render() {
    return (
      <PlacesAutocomplete
        value={this.state.address}
        onChange={this.handleChange}
        onSelect={this.handleSelect}
      >
        {({ getInputProps, suggestions, getSuggestionItemProps, loading }) => (
          <div>
            <input
              {...getInputProps({
                placeholder: 'Search Places ...',
                className: 'location-search-input',
              })}
            />
            <div className="autocomplete-dropdown-container">
              {loading && <div>Loading...</div>}
              {suggestions.map(suggestion => {
                const className = suggestion.active
                  ? 'suggestion-item--active'
                  : 'suggestion-item';
                // inline style for demonstration purpose
                const style = suggestion.active
                  ? { backgroundColor: '#fafafa', cursor: 'pointer' }
                  : { backgroundColor: '#ffffff', cursor: 'pointer' };
                return (
                  <div
                    {...getSuggestionItemProps(suggestion, {
                      className,
                      style,
                    })}
                  >
                    <span>{suggestion.description}</span>
                  </div>
                );
              })}
            </div>
          </div>
        )}
      </PlacesAutocomplete>
    );
  }
}

Props

PlacesAutocomplete is a Controlled Component with a Render Prop. Therefore, you MUST pass at least value and onChange callback to the input element, and render function via children.

| Prop | Type | Required | Description | | ------------------------------------------------------- | :------: | :----------------: | ------------------------------------------------------------------------------------------------ | | value | string | :white_check_mark: | value for the input element | | onChange | function | :white_check_mark: | onChange function for the input element | | children | function | :white_check_mark: | Render function to specify the rendering | | onSelect | function | | Event handler to handle user's select event | | onError | function | | Error handler function that gets called when Google Maps API responds with an error | | searchOptions | object | | Options to Google Maps API (i.e. bounds, radius) | | debounce | number | | Number of milliseconds to delay before making a call to Google Maps API | | highlightFirstSuggestion | boolean | | If set to true, first list item in the dropdown will be automatically highlighted | | shouldFetchSuggestions | boolean | | Component will hit Google Maps API only if this flag is set true | | googleCallbackName | string | | You can provide a callback name to initialize PlacesAutocomplete after google script is loaded |

<a name="value"></a>

value

Type: string, Required: true

<a name="onChange"></a>

onChange

Type: function, Required: true

Typically this event handler will update value state.

<PlacesAutocomplete
  value={this.state.value}
  onChange={value => this.setState({ value })}
>
  {/* custom render function */}
</PlacesAutocomplete>

<a name="children"></a>

children

Type: function Required: true

This is where you render whatever you want to based on the state of PlacesAutocomplete. The function will take an object with the following keys.

• getInputProps : function
• getSuggestionItemProps : function
• loading : boolean
• suggestions : array

Simple example

const renderFunc = ({ getInputProps, getSuggestionItemProps, suggestions }) => (
  <div className="autocomplete-root">
    <input {...getInputProps()} />
    <div className="autocomplete-dropdown-container">
      {loading && <div>Loading...</div>}
      {suggestions.map(suggestion => (
        <div {...getSuggestionItemProps(suggestion)}>
          <span>{suggestion.description}</span>
        </div>
      ))}
    </div>
  </div>
);

// In render function
<PlacesAutocomplete value={this.state.value} onChange={this.handleChange}>
  {renderFunc}
</PlacesAutocomplete>;

getInputProps

This function will return the props that you can spread over the <input /> element. You can optionally call the function with an object to pass other props to the input.

// In render function
<input {...getInputProps({ className: 'my-input', autoFocus: true })} />

getSuggestionItemProps

This function will return the props that you can spread over each suggestion item in your autocomplete dropdown. You MUST call it with suggestion object as an argument, and optionally pass an object to pass other props to the element.

// Simple example
<div className="autocomplete-dropdown">
  {suggestions.map(suggestion => (
    <div {...getSuggestionItemProps(suggestion)}>
      {suggestion.description}
    </div>
  ))}
</div>

// Pass options as a second argument
<div className="autocomplete-dropdown">
  {suggestions.map(suggestion => {
    const className = suggestion.active ? 'suggestion-item--active' : 'suggestion-item';
    return (
      <div {...getSuggestionItemProps(suggestion, { className })}>
        {suggestion.description}
      </div>
    );
  })}
</div>

loading

This is a boolean flag indicating whether or not the request is pending, or has completed.

suggestions

This is an array of suggestion objects each containing all the data from Google Maps API and other metadata.

An example of a suggestion object.

{
  active: false,
  description: "San Francisco, CA, USA",
  formattedSuggestion: { mainText: "San Francisco", secondaryText: "CA, USA" },
  id: "1b9ea3c094d3ac23c9a3afa8cd4d8a41f05de50a",
  index: 0,
  matchedSubstrings: [ {length: