https://github.com/mlane/use-google-places-suggestions
A lightweight React hook for Google Places autocomplete using the modern AutocompleteSuggestion API.
https://github.com/mlane/use-google-places-suggestions
address-autocomplete autocomplete autocomplete-suggestion autocomplete-suggestions geocoder geocoding google-maps google-places hook location-search places-api react react-hook
Last synced: 3 months ago
JSON representation
A lightweight React hook for Google Places autocomplete using the modern AutocompleteSuggestion API.
- Host: GitHub
- URL: https://github.com/mlane/use-google-places-suggestions
- Owner: mlane
- License: mit
- Created: 2025-11-13T20:57:40.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-06T18:52:50.000Z (4 months ago)
- Last Synced: 2026-03-02T07:51:32.788Z (3 months ago)
- Topics: address-autocomplete, autocomplete, autocomplete-suggestion, autocomplete-suggestions, geocoder, geocoding, google-maps, google-places, hook, location-search, places-api, react, react-hook
- Language: TypeScript
- Homepage:
- Size: 200 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# use-google-places-suggestions
[](https://www.npmjs.com/package/use-google-places-suggestions)
[](https://bundlephobia.com/package/use-google-places-suggestions)
A lightweight, zero-dependency React hook for Google Places Autocomplete using the modern [**AutocompleteSuggestion API**](https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data#AutocompleteSuggestion). It handles talking to Google, debouncing, and `sessionStorage` caching; your UI and state stay in your app. Inspired by [`use-places-autocomplete`](https://github.com/wellyshen/use-places-autocomplete), but deliberately UI-agnostic.
```bash
npm install use-google-places-suggestions
```
You are responsible for loading the Google Maps JavaScript API with Places and `AutocompleteSuggestion` before using this hook.
Automated tests are currently in progress and will be added in an upcoming release.
## How it works
You pass a controlled `value` string into the hook (plus optional `cacheExpiration`, `cacheKey`, and `config`). The hook waits for `window.google.maps.places.AutocompleteSuggestion`, debounces calls to `fetchAutocompleteSuggestions`, caches results per lowercased query in `sessionStorage`, and returns `isLoading`, `onClear`, `onSelectPrediction`, and `predictions` for you to wire into your UI.
`cacheKey`, `cacheExpiration`, and [config](https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data#AutocompleteRequest) are expected to be stable per hook instance. If you need different settings (e.g. domestic vs international), use separate `useGooglePlacesSuggestions` instances rather than changing options dynamically.
```tsx
import { useState } from 'react'
import {
getGooglePlacesGeocode,
getGooglePlacesGeocodeLatLng,
useGooglePlacesSuggestions,
} from 'use-google-places-suggestions'
export const Geocoder = () => {
const [value, setValue] = useState('')
const { isLoading, onClear, onSelectPrediction, predictions } =
useGooglePlacesSuggestions({
value,
// cacheExpiration: 24 * 60 * 60, // optional (seconds, default 24h)
// cacheKey: 'ugps', // optional
// config: { types: ['address'] } // optional AutocompleteRequest options
})
const onChange = (event: React.ChangeEvent) => {
const updatedValue = event.currentTarget.value
setValue(updatedValue)
if (!updatedValue.trim()) onClear()
}
const onClick = (
prediction: google.maps.places.AutocompleteSuggestion['placePrediction']
) => {
onSelectPrediction(prediction)
if (!prediction?.text?.text) return
/**
* Gets the geocoder result from a Google Places geocoder request.
* @param request - The geocoder request.
* @returns The geocoder result.
* @see https://developers.google.com/maps/documentation/javascript/geocoding
*/
getGooglePlacesGeocode({
address: prediction?.text?.text,
}).then(results => {
const first = results?.[0]
if (!first) return
/**
* Gets the latitude and longitude from a Google Places geocoder result.
* @param result - The geocoder result.
* @returns The latitude and longitude as a LatLngLiteral.
*/
const latLng = getGooglePlacesGeocodeLatLng(first)
})
}
return (
{predictions?.map(prediction => (
onClick(prediction)}
>
{prediction?.text?.text}
))}
)
}
```
## Contributors
Issues and small, focused PRs are welcome, especially around the [AutocompleteSuggestion flow](https://developers.google.com/maps/documentation/javascript/reference/autocomplete-data#AutocompleteSuggestion), caching, or geocoding helpers.
## License
[MIT](./LICENSE)