react-places-autocomplete
A React component to build a customized UI for Google Maps Places Autocomplete (Demo)
Features
- Enable you to easily build a customized autocomplete dropdown powered by Google Maps Places Library
- Utility functions to geocode and get latitude and longitude using Google Maps Geocoder API
- Pass through arbitrary props to the input element to integrate well with other libraries (e.g. Redux-Form)
Installation
To install the stable version
yarn add react-places-autocomplete
or
npm install react-places-autocomplete --save
The React component is exported as a default export
geocodeByAddress
and geocodeByPlaceId
utility functions are named exports
Demo
See live demo: kenny-hibino.github.io/react-places-autocomplete/
To build the example locally, clone this repo and then run:
npm run demo
Getting Started
To use this component, you are going to need to load Google Maps JavaScript API
Load the library in your project
Declare your PlacesAutocomplete component using React component
Component { superprops thisstate = address: 'San Francisco, CA' this this } { event } { const inputProps = value: thisstateaddress onChange: thisonChange return <form onSubmit=thishandleFormSubmit> <PlacesAutocomplete inputProps=inputProps /> <button type="submit">Submit</button> </form> }
PlacesAutocomplete
Props for Required Props:
Optional Props:
autocompleteItem
classNames
styles
onError
clearItemsOnError
onSelect
onEnterKeyDown
options
debounce
highlightFirstSuggestion
googleLogo
googleLogoType
inputProps
Type: Object
,
Required: true
PlacesAutocomplete is a controlled component. Therefore, you MUST pass at least value
and onChange
callback to the input element.
You can pass arbitrary props to the input element thorough inputProps
object (NOTE: className
and style
props for the input element should be passed through classNames.input
and styles.input
respectively).
const inputProps = value // `value` is required onChange // `onChange` is required { console } type: 'search' placeholder: 'Search Places...' autoFocus: true
autocompleteItem
Type: Functional React Component
,
Required: false
The function takes props with suggestion
, formattedSuggestion
keys (see the example below).
We highly recommend that you create your own custom AutocompleteItem
and pass it as a prop.
/*********************************************** Example #1 autocompleteItem example with `suggestion`************************************************/ { const AutocompleteItem = <div><i className="fa fa-map-marker"/>suggestion</div> return <PlacesAutocomplete inputProps=inputProps autocompleteItem=AutocompleteItem /> } /*************************************************** Example #2 autocompleteItem example with `formattedSuggestion`****************************************************/ { const AutocompleteItem = <div> <strong> formattedSuggestionmainText </strong>' ' <small> formattedSuggestionsecondaryText </small> </div> return <PlacesAutocomplete inputProps=inputProps autocompleteItem=AutocompleteItem /> }
classNames
Type: Object
,
Required: false
You can give a custom css classes to elements.
Accepted keys are root
, input
, autocompleteContainer
, autocompleteItem
, autocompleteItemActive
, googleLogoContainer
, googleLogoImage
.
If you pass classNames
props, none of the default inline styles nor inline styles from styles
prop will
be applied to the element, and you will have full control over styling via CSS.
// classNames example { const cssClasses = root: 'form-group' input: 'form-control' autocompleteContainer: 'my-autocomplete-container' return <PlacesAutocomplete inputProps=inputProps classNames=cssClasses /> }
Now you can easily apply custom CSS styles using the classNames!
styles
Type Object
,
Required: false
You can provide custom inline styles to elements.
Accepted keys are root
, input
, autocompleteContainer
, autocompleteItem
, autocompleteItemActive
, googleLogoContainer
, googleLogoImage
.
const defaultStyles = root: position: 'relative' paddingBottom: '0px' input: display: 'inline-block' width: '100%' padding: '10px' autocompleteContainer: position: 'absolute' top: '100%' backgroundColor: 'white' border: '1px solid #555555' width: '100%' autocompleteItem: backgroundColor: '#ffffff' padding: '10px' color: '#555555' cursor: 'pointer' autocompleteItemActive: backgroundColor: '#fafafa' googleLogoContainer: textAlign: 'right' padding: '1px' backgroundColor: '#fafafa' googleLogoImage: width: 150
Object passed via styles
prop will be merged in with the above defaults and applied to their respective elements.
NOTE: Passing classNames
will disable any inline styling for respective elements.
// custom style examples { const myStyles = root: position: 'absolute' input: width: '100%' autocompleteContainer: backgroundColor: 'green' autocompleteItem: color: 'black' autocompleteItemActive: color: 'blue' return <PlacesAutocomplete inputProps=inputProps styles=myStyles /> }
onError
Type: Function
Required: false
You can pass onError
prop to customize the behavior when google.maps.places.PlacesServiceStatus is not OK
(e.g., no predictions are found)
Function takes status
as a parameter
clearItemsOnError
Type: Boolean
Required: false
Default: false
You can pass clearItemsOnError
prop to indicate whether the autocomplete predictions should be cleared when google.maps.places.PlacesServiceStatus
is not OK
onSelect
Type: Function
Required: false
,
Default: null
You can pass a function that gets called instead of onChange
function when user
hits the Enter key or clicks on an autocomplete item.
The function takes two positional arguments. First argument is address
, second is placeId
.
const handleSelect = { this // You can do other things with address string or placeId. For example, geocode :)} // Pass this function via onSelect prop.<PlacesAutocomplete inputProps=inputProps onSelect=thishandleSelect/>
onEnterKeyDown
Type: Function
Required: false
Deafult: noop
You can pass a callback function that gets called when pressing down Enter key when no item in the dropdown is selected. The function takes two arguments, the value in the input field and the current list of autocomplete items.
const handleEnter = { const possibleAddress = autocompleteItems && autocompleteItems0 && autocompleteItems0suggestion; } // Pass this function via onEnterKeyDown prop.<PlacesAutocomplete inputProps=inputProps onEnterKeyDown=thishandleEnter/>
options
Type: Object
Required: false
Default: {}
You can fine-tune the settings passed to the AutocompleteService class with options
prop.
This prop accepts an object following the same format as google.maps.places.AutocompletionRequest
(except for input
, which comes from the value of the input field).
// these options will bias the autocomplete predictions toward Sydney, Australia with a radius of 2000 meters,// and limit the results to addresses onlyconst options = location: -34 151 radius: 2000 types: 'address' <PlacesAutocomplete inputProps=inputProps options=options/>
debounce
Type: Number
Required: false
Default: 200
The number of milliseconds to delay before making a call to Google API.
highlightFirstSuggestion
Type: Boolean
Required: false
Default: false
If set to true
, first suggestion in the dropdown will be automatically highlighted.
googleLogo
Type: Boolean
Required: false
Default: true
Allows you to toggle the "powered by Google" logo. For more information on Google's logo requirements, refer to this link: https://developers.google.com/places/web-service/policies
googleLogoType
Type: String
("default" or "inverse")
Required: false
Default: "default"
Allows you to pick right color theme for "powered by Google" logo. Please see Google's API page for more information: https://developers.google.com/places/web-service/policies
Utility Functions
geocodeByAddress
API
/** * Returns a promise * @param * @return */
address
Type: String
,
Required: true
String that gets passed to Google Maps Geocoder
// `results` is an entire payload from Google API.
geocodeByPlaceId
API
/** * Returns a promise * @param * @return */
placeId
Type: String
,
Required: true
String that gets passed to Google Maps Geocoder
// `results` is an entire payload from Google API.
getLatLng
API
/** * Returns a promise * @param * @return */
result
Type: Object
Required: true
One of the element from results
(returned from Google Maps Geocoder)
Discussion
Join us on Gitter if you are interested in contributing!
License
MIT