The Google Maps Places API uses session tokens to group a series of autocomplete requests into a single billing session. Without a token, every keystroke counts as a separate billable request, increasing also the overall billing.

A session starts when the user begins typing and ends when they either select a place or clear the input. At that point the token must be replaced with a fresh one for the next session.

By default, useAutocomplete manages the full session token lifecycle internally. A token is created when the Google Maps library loads and automatically rotated when:

• getPlaceDetails is called (place selected)
• getSuggestions receives an empty string (input cleared)

import { useAutocomplete } from "@/hooks/use-autocomplete";

const { getSuggestions, getPlaceDetails, places } = useAutocomplete(
  process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!
);

// Token is created on load, rotated after each selection or input clear.
// You don't need to do anything.

If you need full control over the session token — for example to share it across multiple hook instances, tie it to your own state management, or implement custom rotation logic — pass sessionToken and onSessionEnd to the hook options:

import { useAutocomplete } from "@/hooks/use-autocomplete";
import { useState, useCallback } from "react";

function useSessionToken() {
  const [token, setToken] = useState(
    () => new google.maps.places.AutocompleteSessionToken()
  );

  const rotate = useCallback(() => {
    setToken(new google.maps.places.AutocompleteSessionToken());
  }, []);

  return { token, rotate };
}

export function CustomAutocomplete() {
  const { token, rotate } = useSessionToken();

  const { getSuggestions, getPlaceDetails, places } = useAutocomplete(
    process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!,
    {
      sessionToken: token,
      onSessionEnd: rotate,
    }
  );

  // ...
}

When sessionToken is provided, the hook enters manual mode:

• It uses the token you provide directly and never creates or rotates tokens internally.
• It keeps an internal ref in sync with the external token, so swapping the prop value is all you need to rotate.
• When a session ends (place selected or input cleared), it calls onSessionEnd instead of rotating the token itself — this is your signal to supply a fresh token.

• Shared token — multiple autocomplete instances that should share the same billing session.
• External state — you already manage tokens in a context, store, or server-side and want the hook to consume them.
• Custom rotation — you want to add analytics, logging, or conditional logic when a session ends.

If none of the above applies, stick with automatic mode.

The <Autocomplete /> component uses useAutocomplete in automatic mode under the hood. Session tokens are created and rotated automatically — no extra props are needed.

import { Autocomplete } from "@/components/ui/autocomplete";

// The <Autocomplete /> component uses automatic mode internally.
// Session tokens are fully managed for you — no extra props needed.

<Autocomplete
  apiKey={process.env.NEXT_PUBLIC_GOOGLE_MAPS_API_KEY!}
  placeholder="Search for an address..."
  onPlaceSelect={(details) => console.log(details)}
/>