Live Demo

Features

Requirement

Installation

$ yarn add use-places-autocomplete# or$ npm install --save use-places-autocomplete

$ yarn add --dev @types/google.maps# or$ npm install --save-dev @types/google.maps

Getting Started

Setup APIs

Load the library

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

Create the component

importusePlacesAutocomplete,{getGeocode,getLatLng,}from"use-places-autocomplete";importuseOnclickOutsidefrom"react-cool-onclickoutside";constPlacesAutocomplete=()=>{const{    ready,    value,suggestions:{ status, data},    setValue,    clearSuggestions,}=usePlacesAutocomplete({callbackName:"YOUR_CALLBACK_NAME",requestOptions:{/* Define search scope here */},debounce:300,});constref=useOnclickOutside(()=>{// When the user clicks outside of the component, we can dismiss// the searched suggestions by calling this methodclearSuggestions();});consthandleInput=(e)=>{// Update the keyword of the input elementsetValue(e.target.value);};consthandleSelect=({ description})=>()=>{// When the user selects a place, we can replace the keyword without request data from API// by setting the second parameter to "false"setValue(description,false);clearSuggestions();// Get latitude and longitude via utility functionsgetGeocode({address:description}).then((results)=>{const{ lat, lng}=getLatLng(results[0]);console.log("📍 Coordinates: ",{ lat, lng});});};constrenderSuggestions=()=>data.map((suggestion)=>{const{        place_id,structured_formatting:{ main_text, secondary_text},}=suggestion;return(<likey={place_id}onClick={handleSelect(suggestion)}><strong>{main_text}</strong><small>{secondary_text}</small></li>);});return(<divref={ref}><inputvalue={value}onChange={handleInput}disabled={!ready}placeholder="Where are you going?"/>{/* We can use the "status" to decide whether we should display the dropdown or not */}{status==="OK"&&<ul>{renderSuggestions()}</ul>}</div>);};

importusePlacesAutocompletefrom"use-places-autocomplete";import{Combobox,ComboboxInput,ComboboxPopover,ComboboxList,ComboboxOption,}from"@reach/combobox";import"@reach/combobox/styles.css";constPlacesAutocomplete=()=>{const{    ready,    value,suggestions:{ status, data},    setValue,}=usePlacesAutocomplete({callbackName:"YOUR_CALLBACK_NAME"});consthandleInput=(e)=>{setValue(e.target.value);};consthandleSelect=(val)=>{setValue(val,false);};return(<ComboboxonSelect={handleSelect}aria-labelledby="demo"><ComboboxInputvalue={value}onChange={handleInput}disabled={!ready}/><ComboboxPopover><ComboboxList>{status==="OK"&&data.map(({ place_id, description})=>(<ComboboxOptionkey={place_id}value={description}/>))}</ComboboxList></ComboboxPopover></Combobox>);};

Lazily Initializing The Hook

Option 1, manually initialize the hook:

importusePlacesAutocompletefrom"use-places-autocomplete";constApp=()=>{const{ init}=usePlacesAutocomplete({initOnMount:false,// Disable initializing when the component mounts, default is true});const[loading]=useGoogleMapsApi({library:"places",onLoad:()=>init(),// Lazily initializing the hook when the script is ready});return<div>{/* Some components... */}</div>;};

Option 2, wrap the hook into a conditional component:

importusePlacesAutocompletefrom"use-places-autocomplete";constPlacesAutocomplete=()=>{const{ ready, value, suggestions, setValue}=usePlacesAutocomplete();return<div>{/* Some components... */}</div>;};constApp=()=>{const[loading]=useGoogleMapsApi({library:"places"});return(<div>{!loading ?<PlacesAutocomplete/> :null}{/* Other components... */}</div>);};

Cache Data For You

constmethods=usePlacesAutocomplete({// Provide the cache time in seconds, the default is 24 hourscache:24*60*60,});

Custom cache key

constmethods=usePlacesAutocomplete({// Provide a custom cache keycacheKey:"region-restricted",});

API

constreturnObj=usePlacesAutocomplete(parameterObj);

Parameter object (optional)

Return object

suggestions

setValue

importusePlacesAutocompletefrom"use-places-autocomplete";constPlacesAutocomplete=()=>{const{ value, setValue}=usePlacesAutocomplete();consthandleInput=(e)=>{// Place a "string" to update the value of the input elementsetValue(e.target.value);};return(<div><inputvalue={value}onChange={handleInput}/>{/* Render dropdown */}</div>);};

importusePlacesAutocompletefrom"use-places-autocomplete";constPlacesAutocomplete=()=>{const{    value,suggestions:{ status, data},    setValue,}=usePlacesAutocomplete();consthandleSelect=({ description})=>()=>{// When the user selects a place, we can replace the keyword without requesting data from the API// by setting the second parameter to "false"setValue(description,false);};constrenderSuggestions=()=>data.map((suggestion)=>(<likey={suggestion.place_id}onClick={handleSelect(suggestion)}>{/* Render suggestion text */}</li>));return(<div><inputvalue={value}onChange={handleInput}/>{status==="OK"&&<ul>{renderSuggestions()}</ul>}</div>);};

clearSuggestions

importusePlacesAutocompletefrom"use-places-autocomplete";importuseOnclickOutsidefrom"react-cool-onclickoutside";constPlacesAutocomplete=()=>{const{    value,suggestions:{ status, data},    setValue,    clearSuggestions,}=usePlacesAutocomplete();constref=useOnclickOutside(()=>{// When the user clicks outside of the component, call it to clear and reset the suggestions dataclearSuggestions();});constrenderSuggestions=()=>data.map((suggestion)=>(<likey={suggestion.place_id}onClick={handleSelect(suggestion)}>{/* Render suggestion text */}</li>));return(<divref={ref}><inputvalue={value}onChange={handleInput}/>{/* After calling the clearSuggestions(), the "status" is reset so the dropdown is hidden */}{status==="OK"&&<ul>{renderSuggestions()}</ul>}</div>);};

Utility Functions

getGeocode

import{getGeocode}from"use-places-autocomplete";constparameter={address:"Section 5, Xinyi Road, Xinyi District, Taipei City, Taiwan",// orplaceId:"ChIJraeA2rarQjQRPBBjyR3RxKw",};getGeocode(parameter).then((results)=>{console.log("Geocoding results: ",results);}).catch((error)=>{console.log("Error: ",error);});

getLatLng

import{getGeocode,getLatLng}from"use-places-autocomplete";constparameter={address:"Section 5, Xinyi Road, Xinyi District, Taipei City, Taiwan",};getGeocode(parameter).then((results)=>{const{ lat, lng}=getLatLng(results[0]);console.log("Coordinates: ",{ lat, lng});});

getZipCode

import{getGeocode,getZipCode}from"use-places-autocomplete";constparameter={address:"Section 5, Xinyi Road, Xinyi District, Taipei City, Taiwan",};getGeocode(parameter)// By default we use the "long_name" value from API response, you can tell the utility to use "short_name"// by setting the second parameter to "true".then((results)=>{constzipCode=getZipCode(results[0],false);console.log("ZIP Code: ",zipCode);});

getDetails

importusePlacesAutocomplete,{getDetails}from"use-places-autocomplete";constPlacesAutocomplete=()=>{const{ suggestions, value, setValue}=usePlacesAutocomplete();consthandleInput=(e)=>{// Place a "string" to update the value of the input elementsetValue(e.target.value);};constsubmit=()=>{constparameter={// Use the "place_id" of suggestion from the dropdown (object), here just taking the first suggestion for brevityplaceId:suggestions[0].place_id,// Specify the return data that you want (optional)fields:["name","rating"],};getDetails(parameter).then((details)=>{console.log("Details: ",details);}).catch((error)=>{console.log("Error: ",error);});};return(<div><inputvalue={value}onChange={handleInput}/>{/* Render dropdown */}<buttononClick={submit}>Submit Suggestion</button></div>);};

Articles / Blog Posts

Contributors ✨