Material-UI React component that provides suggestions/autocompletes places using the Google Places API
npm install mui-places-autocomplete```
yarn add mui-places-autocomplete --ignore-scripts
or
``
npm install mui-places-autocomplete --save --ignore-scripts
Note that if you exclude the --ignore-scripts option when installing a package then the prepublish script in package.json is ran after installing locally. Tests are ran as part of the prepublish script and they will fail if you haven't yet set a Google API key to the enivronment variables GOOGLE_API_KEY or GOOGLE_API_TEST_KEY (see setup section).
To see a demo of this component locally clone this repository and run:
``
yarn demo
or
``
npm run demo
javascript
import React from 'react'
import SomeCoolComponent from 'some-cool-component'
import MUIPlacesAutocomplete from 'mui-places-autocomplete'class Example extends React.Component {
constructor() {
super()
this.onSuggestionSelected = this.onSuggestionSelected.bind(this)
}
onSuggestionSelected(suggestion) {
// Add your business logic here. In this case we just log...
console.log('Selected suggestion:', suggestion)
}
render() {
// Use 'renderTarget' prop to render a component/target we want the suggestions to popover
return (
onSuggestionSelected={this.onSuggestionSelected}
renderTarget={() => ( )}
/>
)
}
}
export default Example
`$3
* DemoControlledInput.jsx - Example that shows how to control the
element as well as integrate with Redux Form.
* DemoGeocodeLatLong.jsx - Example that shows how to obtain the latitude/longitude of a selected suggestion.$3
This component relies on some basic setup before usage. It makes use of services provided by Google. To properly make use of the services you will need to do three things:
1. Enable the Google Places API Web Service
2. (Optional) Enable the Google Maps Geocoding API (only required if making use of the geocoding utility functions)
3. Enable the Google Maps JavaScript API
4. Obtain a Google API keyYou can do all of these things from your Google developers console here: https://console.developers.google.com
The component relies on the Places library in the Google Maps JavaScript API. To load the Places library on the client you must add the following to the HTML document you deliver to your clients:
`html
`Be sure that you replace
YOUR_API_KEY with the one you just created or obtained previously.This component also has testing which makes use of the Places library in the Google Maps JavaScript API. Rather than loading the Places library it uses a module provided by Google. It also requires an API key. This key can be provided to a file @
test/api-key.js. If you would like it can also be provided as an environment variable named GOOGLE_API_KEY or GOOGLE_API_TEST_KEY.$3
| Prop | Type | Required | Description |
| :--- | :--- | :---: | :--- |
|
onSuggestionSelected | Function | ✓ | Callback that provides the selected suggestion. |
| renderTarget | Function | ✓ | Renders the components/elements that you would like to have the list of suggestions popover. |
| createAutocompleteRequest | Function | | Returns an object that modifies which suggestions are shown to the user. |
| textFieldProps | Object | | Props that will be spread onto a MUI component that is responsible for rendering the element. If you would like to control the state of the element externally you must set the value key on the object passed to textFieldProps. |
#### onSuggestionSelected (required)
This function will be called everytime a user has selected a suggestion. It has the following signature:
`javascript
function onSuggestionSelected(suggestion)
`This function is invoked during rendering. It ought to return the components/elements that you want the list of suggestions to render (pop) over.
leverages the Google Places API Web Service to provide place suggestions that a user may select from based on the users input. The requests made to the Google Places API Web Service are very simple by default. This results in a wider breadth in the types of suggestions (i.e. an establishment, city/locality, specific address, etc.) returned when the user first starts searching for a place. The set of returned suggestions may also not be geospatially tight ("close to each other"). As the users search becomes more specific the types of suggestions returned start to narrow as well as tighten geospatially around each other.Depending on your use case you may wish to:
* Specify (i.e. narrow) the types of suggestions returned by the Google Places API Web Service
* Bias/restrict the suggestions returned by the Google Places API Web Service to a specific area
You can achieve this by providing a function to the
createAutocompleteRequest prop. The function is called everytime a request for suggestions is made to the Google Places API Web Service. The function passed to the createAutocompleteRequest prop ought to have the following signature:`javascript
function createAutocompleteRequest(inputValue)
`Where:
*
inputValue - The users current search valueIt ought to return an object that specifies what suggestions (i.e. types and bias/area restrictions) should be returned by the Google Places API Web Service. For example:
`javascript
function createAutocompleteRequest(inputValue) {
// Restrict the returned suggestions to those that:
// 1) Are in Bellingham (latitude 48.7519, longitude 122.4787)
// 2) Are within ~3 miles (5000 meters)
// 3) Have an address associated with them
return {
input: inputValue,
types: ['address'],
location: { lat: () => 48.7519, lng: () => 122.4787 },
radius: 5000,
}
}
`The properties that are allowed on the returned object are documented here: AutocompleteRequest API object specification
Note: There is no validation for what is returned from the function provided to the
createAutocompleteRequest prop. So if you don't return an object or set the properties incorrectly then things are going to go poorly. component is used to render the element. It can be customized to meet your needs by supplying an object to the textFieldProps prop. All properties on the object supplied to the textFieldProps prop will be spread onto the component. You can read more about the props that the component accepts here: API documentationtextFieldProps.value control propTo help meet your needs the state of the
element can be controlled externally. It is also useful if you would like to integrate with other 3rd party libraries such as Redux Form. To control the state of the element you must set the value property on the object passed to the textFieldProps prop.`javascript
// 'getState()' can return state from a React component, your app (e.g via Redux), some other source, etc.
const { inputValue } = getState()
`If you would like to have consistency between the controlled
elements state as well as any suggestions that are selected then you need to update the controlled state of the element when a suggestion is selected. There is an example of how to do this in the advanced usage section.$3
is focused on providing functionality for searching for places of interest and providing realtime suggestions to searches. To accomplish this leverages the Google Places API Web Service to provide place suggestions. The place suggestions returned by the Google Places API Web Service doesn't include any geospatial data (i.e. latitude/longitude). Depending on your use case you may require geospatial data about the suggestions.To facilitate consumers of
and their different use cases, geocoding utility functions have been packaged together with the component. Geocoding will allow you to convert addresses into geospatial data/coordinates such as latitude and longitude. For a complete demo showing how to use the geocoding utility functions see the advanced usage section.Note: To make use of the geocoding utility functions you must enable the Google Maps Geocoding API. For more info see the setup section.
Each suggestion returned to
by the Google Places API Web Service has a property named place_id. The place_id property contains a value that uniquely identifies a place in the Google Places database. The place_id property can be used in conjunction with the geocodeByPlaceID() function to get geospatial data for any suggestion.The
geocodeByPlaceID() function has the following signature:`javascript
function geocodeByPlaceID(placeId)
`Where:
*
placeId - Unique identifier for a place in the Google Places databaseThe
geocodeByPlaceID() function returns a promise that contains the results of the request made with the Google Maps Geocoding API.`javascript
import React from 'react'
import SomeCoolComponent from 'some-cool-component'
import MUIPlacesAutocomplete, { geocodeByPlaceID } from 'mui-places-autocomplete'class Example extends React.Component {
constructor() {
super()
// Setup your state here...
this.state = { coordinates: null }
this.onSuggestionSelected = this.onSuggestionSelected.bind(this)
}
onSuggestionSelected(suggestion) {
geocodeByPlaceID(suggestion.place_id).then((results) => {
// Add your business logic here. In this case we simply set our state with the coordinates of
// the selected suggestion...
// Just use the first result in the list to get the geometry coordinates
const { geometry } = results[0]
const coordinates = {
lat: geometry.location.lat(),
lng: geometry.location.lng(),
}
this.setState({ coordinates })
}).catch((err) => {
// Handle any errors that occurred when we tried to get geospatial data for a selected
// suggestion...
})
}
render() {
// Your render logic here...
}
}
export default Example
`The properties that are returned on the array of geocode results are documented here: GeocodeResult API object specification
#### geocodeBySuggestion
The
geocodeBySuggestion() function is a wrapper around the geocodeByPlaceID() function. It has the following signature:`javascript
function geocodeBySuggestion(suggestion)
`Where:
*
suggestion - Object representing a suggestion returned by the Google Places API Web Service which has a property named place_id that uniquely identifies a place in the Google Places database.It has the same behavior as the
geocodeByPlaceID()` function where it returns a promise that contains the results of the request made with the Google Maps Geocoding API.