Basics

Examples

API Reference

Complete reference for the Autocomplete component and useAutocomplete hook.

Autocomplete

<Autocomplete /> wraps the BaseUI Autocomplete, Customizing keyboard navigation and opening logic, using the useAutocomplete hook internally.

Prop	Type	Default	Description
`apiKey`	string	—	Your Google Maps API key with the Places API (New) enabled.
`options`	UseAutocompleteOptions	—	Options passed during Google Maps API setup (language, region, libraries, etc.).
`fetchParams`	FetchParams	—	Parameters passed to every autocomplete suggestion request (e.g. includedPrimaryTypes, locationBias).
`onPlaceSelect`	(details: PlaceDetails) => void	—	Callback fired when a place is selected. Receives parsed place details including street, city, country, postal code, coordinates, and the raw Google Place object.
`debounceMs`	number	200	Debounce delay in milliseconds before fetching suggestions. Helps reduce API calls and improve UX.
`...props`	React.ComponentProps<"input">	—	All standard HTML input attributes are forwarded to the underlying Input component (placeholder, disabled, className, etc.).

The component extends all standard HTML input props. You can pass placeholder, disabled, className, etc. directly.

useAutocomplete()

The useAutocomplete hook provides the full Google Maps Places Autocomplete logic without any UI. Use it to build your own custom autocomplete experience.

const { 
	isLoaded, 
	isStale, 
	error, 
	places, 
	getSuggestions, 
	getPlaceDetails, 
	autocomplete 
} = useAutocomplete(apiKey, options);

Parameters

Prop	Type	Default	Description
`apiKey`	string	—	Your Google Maps API key with the Places API (New) enabled.
`options`	UseAutocompleteOptions	—	Optional configuration for the Google Maps API loader and autocomplete behavior.

UseAutocompleteOptions

Configuration object passed as the second argument to useAutocomplete. Extends the @googlemaps/js-api-loader options. Supports two session token modes:

Automatic (default) — the hook creates and rotates session tokens internally. No extra work required.
Manual — pass your own sessionToken and listen to onSessionEnd to supply a fresh one when a session ends.

Prop	Type	Default	Description
`debounceMs`	number	200	Debounce delay in milliseconds before fetching suggestions.
`sessionToken`	AutocompleteSessionToken	—	When provided, the hook enters in manual mode: it uses this token directly and never creates or rotates tokens internally. Pair with onSessionEnd to know when to supply a fresh token. When omitted, the hook manages the token lifecycle in Automatic mode.
`onSessionEnd`	() => void	—	Called when a session ends (place selected or input cleared). Only relevant in manual mode — use it to rotate the sessionToken you pass in.
`...loaderOptions`	Omit<APIOptions, 'key'>	—	Any additional options supported by @googlemaps/js-api-loader.

Return Value

The hook returns a UseAutocompleteReturn object with the following properties:

Prop	Type	Default	Description
`isLoaded`	boolean	—	Whether the Google Maps Places library has finished loading.
`isStale`	boolean	—	True while new suggestions are being fetched (useful for loading indicators).
`error`	Error \| null	—	Error from the last suggestion fetch, or null.
`places`	PlacePrediction[] \| undefined	—	The current list of autocomplete suggestions. Undefined before any request is made.
`getSuggestions`	(input: string, FetchParams?: FetchParams) => void	—	Fetches autocomplete suggestions for the given input string. Automatically debounced.
`getPlaceDetails`	(prediction: PlacePrediction) => Promise<PlaceDetails>	—	Fetches full place details for a prediction. Ends the current session after each call — in automated mode this rotates the token automatically; in manual mode it fires onSessionEnd.
`autocomplete`	<T>(field: T, FetchParams?) => T & { onChange }	—	Spread helper for react-hook-form. Wraps a field's onChange to trigger getSuggestions automatically.

PlaceDetails

The object returned by getPlaceDetails and passed to onPlaceSelect. Contains parsed address components and the raw Google Place object.

Prop	Type	Default	Description
`formattedAddress`	string \| null	—	The full formatted address string.
`streetNumber`	string \| null	—	The street number (from "street_number" address component).
`route`	string \| null	—	The street name (from "route" address component).
`city`	string \| null	—	The city name (from "locality" address component).
`province`	string \| null	—	The province/state short text (from "administrative_area_level_2").
`region`	string \| null	—	The region/state long text (from "administrative_area_level_1").
`country`	string \| null	—	The country name (from "country" address component).
`postalCode`	string \| null	—	The postal/zip code (from "postal_code" address component).
`location`	LatLngLiteral \| null	—	The geographic coordinates of the place ({ lat, lng }).
`placeId`	string	—	The Google Place ID of the selected prediction.
`place`	google.maps.places.Place	—	The raw Google Maps Place object with all fetched fields.

FetchParams

Options passed to each suggestion fetch request. It accepts:Omit<google.maps.places.AutocompleteRequest, 'input' | 'sessionToken'>.

Prop	Type	Default	Description
`includedPrimaryTypes`	string[]	—	Restrict results to specific place types (e.g. ["route"], ["address"], ["establishment"]).
`includedRegionCodes`	string[]	—	Restrict results to specific countries/regions (e.g. ["us", "ca"]).
`locationBias`	LocationBias	—	Bias results toward a specific location (circle, rectangle, or LatLng).
`locationRestriction`	LocationRestriction	—	Restrict results to a specific geographic area.
`inputOffset`	number	—	zero-based Unicode character offset of input indicating the cursor position in input.
`origin`	google.maps.LatLng \| google.maps.LatLngLiteral \| undefined	—	The origin point from which to calculate geodesic distance.

getSuggestions()

Fetches autocomplete suggestions for the given input string. Results are stored in places. It accepts FetchParams as the second argument.

const { getSuggestions, places } = useAutocomplete(apiKey);

// Basic usage
getSuggestions("1600 Amphitheatre");

// With request options
getSuggestions("1600 Amphitheatre", {
  includedPrimaryTypes: ["route"],
  includedRegionCodes: ["us"],
});

Passing an empty string clears the current suggestions and ends the session — in automatic mode the token is rotated automatically; in manual mode onSessionEnd is fired so you can supply a fresh token.

getPlaceDetails()

Fetches full place details for a given prediction. Returns a PlaceDetails object with parsed address components, coordinates, and the raw Place object.

const { getPlaceDetails } = useAutocomplete(apiKey);

const handleSelect = async (prediction: PlacePrediction) => {
  const details = await getPlaceDetails(prediction);

  console.log(details.formattedAddress);
  console.log(details.city, details.country);
  console.log(details.location); // { lat, lng }
  console.log(details.place);    // raw Place object
};

After each call, the current session ends and the suggestions list is cleared. In automatic mode the token is rotated automatically; in manual mode onSessionEnd is fired. This keeps Google Maps API billing efficient by bundling autocomplete requests into sessions.

autocomplete()

A spread helper designed for react-hook-form integration with your custom UI. It takes the field object to trigger getSuggestions automatically while preserving the original handler.

const { places, autocomplete } = useAutocomplete(apiKey);

// With react-hook-form
<Controller
  control={form.control}
  name="street"
  render={({ field }) => (
    <Input {...autocomplete(field, { includedPrimaryTypes: ["route"] })} />
	<p>Output: {places.length || 0}</p>
  )}
/>

Installation Session Token

Basics

Examples

API Reference

Complete reference for the Autocomplete component and useAutocomplete hook.

Autocomplete

<Autocomplete /> wraps the BaseUI Autocomplete, Customizing keyboard navigation and opening logic, using the useAutocomplete hook internally.

Prop	Type	Default	Description
`apiKey`	string	—	Your Google Maps API key with the Places API (New) enabled.
`options`	UseAutocompleteOptions	—	Options passed during Google Maps API setup (language, region, libraries, etc.).
`fetchParams`	FetchParams	—	Parameters passed to every autocomplete suggestion request (e.g. includedPrimaryTypes, locationBias).
`onPlaceSelect`	(details: PlaceDetails) => void	—	Callback fired when a place is selected. Receives parsed place details including street, city, country, postal code, coordinates, and the raw Google Place object.
`debounceMs`	number	200	Debounce delay in milliseconds before fetching suggestions. Helps reduce API calls and improve UX.
`...props`	React.ComponentProps<"input">	—	All standard HTML input attributes are forwarded to the underlying Input component (placeholder, disabled, className, etc.).

The component extends all standard HTML input props. You can pass placeholder, disabled, className, etc. directly.

useAutocomplete()

The useAutocomplete hook provides the full Google Maps Places Autocomplete logic without any UI. Use it to build your own custom autocomplete experience.

const { 
	isLoaded, 
	isStale, 
	error, 
	places, 
	getSuggestions, 
	getPlaceDetails, 
	autocomplete 
} = useAutocomplete(apiKey, options);

Parameters

Prop	Type	Default	Description
`apiKey`	string	—	Your Google Maps API key with the Places API (New) enabled.
`options`	UseAutocompleteOptions	—	Optional configuration for the Google Maps API loader and autocomplete behavior.

UseAutocompleteOptions

Configuration object passed as the second argument to useAutocomplete. Extends the @googlemaps/js-api-loader options. Supports two session token modes:

Automatic (default) — the hook creates and rotates session tokens internally. No extra work required.
Manual — pass your own sessionToken and listen to onSessionEnd to supply a fresh one when a session ends.

Prop	Type	Default	Description
`debounceMs`	number	200	Debounce delay in milliseconds before fetching suggestions.
`sessionToken`	AutocompleteSessionToken	—	When provided, the hook enters in manual mode: it uses this token directly and never creates or rotates tokens internally. Pair with onSessionEnd to know when to supply a fresh token. When omitted, the hook manages the token lifecycle in Automatic mode.
`onSessionEnd`	() => void	—	Called when a session ends (place selected or input cleared). Only relevant in manual mode — use it to rotate the sessionToken you pass in.
`...loaderOptions`	Omit<APIOptions, 'key'>	—	Any additional options supported by @googlemaps/js-api-loader.

Return Value

The hook returns a UseAutocompleteReturn object with the following properties:

Prop	Type	Default	Description
`isLoaded`	boolean	—	Whether the Google Maps Places library has finished loading.
`isStale`	boolean	—	True while new suggestions are being fetched (useful for loading indicators).
`error`	Error \| null	—	Error from the last suggestion fetch, or null.
`places`	PlacePrediction[] \| undefined	—	The current list of autocomplete suggestions. Undefined before any request is made.
`getSuggestions`	(input: string, FetchParams?: FetchParams) => void	—	Fetches autocomplete suggestions for the given input string. Automatically debounced.
`getPlaceDetails`	(prediction: PlacePrediction) => Promise<PlaceDetails>	—	Fetches full place details for a prediction. Ends the current session after each call — in automated mode this rotates the token automatically; in manual mode it fires onSessionEnd.
`autocomplete`	<T>(field: T, FetchParams?) => T & { onChange }	—	Spread helper for react-hook-form. Wraps a field's onChange to trigger getSuggestions automatically.

PlaceDetails

The object returned by getPlaceDetails and passed to onPlaceSelect. Contains parsed address components and the raw Google Place object.

Prop	Type	Default	Description
`formattedAddress`	string \| null	—	The full formatted address string.
`streetNumber`	string \| null	—	The street number (from "street_number" address component).
`route`	string \| null	—	The street name (from "route" address component).
`city`	string \| null	—	The city name (from "locality" address component).
`province`	string \| null	—	The province/state short text (from "administrative_area_level_2").
`region`	string \| null	—	The region/state long text (from "administrative_area_level_1").
`country`	string \| null	—	The country name (from "country" address component).
`postalCode`	string \| null	—	The postal/zip code (from "postal_code" address component).
`location`	LatLngLiteral \| null	—	The geographic coordinates of the place ({ lat, lng }).
`placeId`	string	—	The Google Place ID of the selected prediction.
`place`	google.maps.places.Place	—	The raw Google Maps Place object with all fetched fields.

FetchParams

Options passed to each suggestion fetch request. It accepts:Omit<google.maps.places.AutocompleteRequest, 'input' | 'sessionToken'>.

Prop	Type	Default	Description
`includedPrimaryTypes`	string[]	—	Restrict results to specific place types (e.g. ["route"], ["address"], ["establishment"]).
`includedRegionCodes`	string[]	—	Restrict results to specific countries/regions (e.g. ["us", "ca"]).
`locationBias`	LocationBias	—	Bias results toward a specific location (circle, rectangle, or LatLng).
`locationRestriction`	LocationRestriction	—	Restrict results to a specific geographic area.
`inputOffset`	number	—	zero-based Unicode character offset of input indicating the cursor position in input.
`origin`	google.maps.LatLng \| google.maps.LatLngLiteral \| undefined	—	The origin point from which to calculate geodesic distance.

getSuggestions()

Fetches autocomplete suggestions for the given input string. Results are stored in places. It accepts FetchParams as the second argument.

const { getSuggestions, places } = useAutocomplete(apiKey);

// Basic usage
getSuggestions("1600 Amphitheatre");

// With request options
getSuggestions("1600 Amphitheatre", {
  includedPrimaryTypes: ["route"],
  includedRegionCodes: ["us"],
});

getPlaceDetails()

Fetches full place details for a given prediction. Returns a PlaceDetails object with parsed address components, coordinates, and the raw Place object.

const { getPlaceDetails } = useAutocomplete(apiKey);

const handleSelect = async (prediction: PlacePrediction) => {
  const details = await getPlaceDetails(prediction);

  console.log(details.formattedAddress);
  console.log(details.city, details.country);
  console.log(details.location); // { lat, lng }
  console.log(details.place);    // raw Place object
};

autocomplete()

A spread helper designed for react-hook-form integration with your custom UI. It takes the field object to trigger getSuggestions automatically while preserving the original handler.

const { places, autocomplete } = useAutocomplete(apiKey);

// With react-hook-form
<Controller
  control={form.control}
  name="street"
  render={({ field }) => (
    <Input {...autocomplete(field, { includedPrimaryTypes: ["route"] })} />
	<p>Output: {places.length || 0}</p>
  )}
/>

Installation Session Token

API Reference

Autocomplete

useAutocomplete()

Parameters

UseAutocompleteOptions

Return Value

PlaceDetails

FetchParams

getSuggestions()

getPlaceDetails()

autocomplete()

Loading

API Reference

Autocomplete

useAutocomplete()

Parameters

UseAutocompleteOptions

Return Value

PlaceDetails

FetchParams

getSuggestions()

getPlaceDetails()

autocomplete()