{"id":11710,"library":"react-google-autocomplete","title":"React Google Autocomplete & Places Hooks","description":"The `react-google-autocomplete` package provides flexible tools for integrating Google Places Autocomplete functionality into React applications. It offers a high-level `Autocomplete` component for quick setup, and lower-level hooks (`usePlacesWidget`, `usePlacesAutocompleteService`) for more control over UI and API interactions. The `usePlacesWidget` hook allows attaching autocomplete behavior to any input element via a ref, while `usePlacesAutocompleteService` provides direct programmatic access to the Google Places Autocomplete Service, including debounce functionality to optimize API requests. The current stable version is 2.7.5, with an active release cadence involving frequent minor and patch updates. Key differentiators include the dual approach of providing both a ready-to-use component and advanced hooks, built-in debounce, and comprehensive TypeScript types.","status":"active","version":"2.7.5","language":"javascript","source_language":"en","source_url":"https://github.com/ErrorPro/react-google-autocomplete","tags":["javascript","react","google","autocomplete","react google autocomplete","react google","react autocomplete","google autocomplete","react google places autocomplete","typescript"],"install":[{"cmd":"npm install react-google-autocomplete","lang":"bash","label":"npm"},{"cmd":"yarn add react-google-autocomplete","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-google-autocomplete","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency required for all React applications.","package":"react","optional":false}],"imports":[{"note":"`Autocomplete` is exported as a default export.","wrong":"import { Autocomplete } from 'react-google-autocomplete';","symbol":"Autocomplete","correct":"import Autocomplete from 'react-google-autocomplete';"},{"note":"`usePlacesWidget` is a named export, common for React hooks.","wrong":"import usePlacesWidget from 'react-google-autocomplete';","symbol":"usePlacesWidget","correct":"import { usePlacesWidget } from 'react-google-autocomplete';"},{"note":"`usePlacesAutocompleteService` is a named export for programmatic control.","wrong":"import usePlacesAutocompleteService from 'react-google-autocomplete';","symbol":"usePlacesAutocompleteService","correct":"import { usePlacesAutocompleteService } from 'react-google-autocomplete';"},{"note":"Import types explicitly for type-checking when using TypeScript.","symbol":"Types for PlaceResult","correct":"import type { PlaceResult } from 'react-google-autocomplete';"}],"quickstart":{"code":"import Autocomplete from \"react-google-autocomplete\";\nimport React from 'react';\n\nfunction MyAutocompleteComponent() {\n  // Replace with your actual Google Maps API key or use environment variables\n  // Ensure GOOGLE_MAPS_API_KEY is defined in your environment or .env file\n  const YOUR_GOOGLE_MAPS_API_KEY = process.env.GOOGLE_MAPS_API_KEY ?? '';\n\n  if (!YOUR_GOOGLE_MAPS_API_KEY) {\n    console.error('GOOGLE_MAPS_API_KEY is not defined. Please provide your API key.');\n    return <div>API Key missing. Please set GOOGLE_MAPS_API_KEY.</div>;\n  }\n\n  return (\n    <div style={{ padding: '20px', maxWidth: '600px', margin: 'auto' }}>\n      <h1>Search for a Place</h1>\n      <p>Start typing an address or place name below:</p>\n      <Autocomplete\n        apiKey={YOUR_GOOGLE_MAPS_API_KEY}\n        onPlaceSelected={(place, inputRef, autocompleteRef) => {\n          console.log(\"Selected Place:\", place);\n          if (place.geometry && place.geometry.location) {\n            console.log(\"Latitude:\", place.geometry.location.lat());\n            console.log(\"Longitude:\", place.geometry.location.lng());\n          }\n          console.log(\"Full Address:\", place.formatted_address);\n        }}\n        options={{\n          types: [\"(cities)\"], // Example: restrict to cities\n          fields: [\"address_components\", \"geometry\", \"icon\", \"name\", \"place_id\", \"formatted_address\"]\n        }}\n        placeholder=\"Enter a city or location\"\n        style={{ \n          width: '100%', \n          padding: '10px',\n          fontSize: '16px',\n          border: '1px solid #ccc',\n          borderRadius: '4px'\n        }}\n        className=\"my-autocomplete-input\"\n      />\n      <p style={{ marginTop: '20px', fontSize: '0.9em', color: '#666' }}>\n        Ensure the Google Maps JavaScript API and Places API are enabled for your key.\n      </p>\n    </div>\n  );\n}\n\nexport default MyAutocompleteComponent;","lang":"javascript","description":"This quickstart demonstrates how to use the `Autocomplete` component with a Google Maps API key to integrate Google Places Autocomplete, logging selected place details to the console."},"warnings":[{"fix":"For new projects or extensive customization, prefer `usePlacesWidget` or `usePlacesAutocompleteService`. Refer to the documentation for hook-specific usage and integration patterns.","message":"Version 2.1.0 introduced new hooks (`usePlacesWidget`, `usePlacesAutocompleteService`) that offer more control but represent a significant shift from the component-based approach for custom implementations. While the `Autocomplete` component remains, developers seeking granular control or custom UI will need to adapt to the new hook API.","severity":"breaking","affected_versions":">=2.1.0"},{"fix":"Verify that both 'Maps JavaScript API' and 'Places API' are enabled in your Google Cloud Console. If manually loading the script, ensure the URL includes `&libraries=places`. If using the `apiKey` prop, ensure the API key is correct and associated with a project where these APIs are active.","message":"Correct Google Maps API Key and Library setup is crucial. The Google Cloud project associated with your API key must have both 'Maps JavaScript API' and 'Places API' enabled. Additionally, if manually loading the Google Maps script, the `&libraries=places` parameter is mandatory.","severity":"gotcha","affected_versions":"All"},{"fix":"Choose one method for loading the Google Maps script: either pass the `apiKey` prop to the `Autocomplete` component/hooks OR manually include the script with `libraries=places` in your `index.html`. Do not do both simultaneously unless specifically handling script loading lifecycle.","message":"Conflicting Google Maps Script Loading: The package can automatically load the Google Maps script if you provide the `apiKey` prop. However, if you also manually include the Google Maps script in your `index.html` or similar, this can lead to conflicts and unexpected behavior or errors.","severity":"gotcha","affected_versions":"All"},{"fix":"Always specify required fields in the `options.fields` prop, for example: `options={{ fields: [\"formatted_address\", \"geometry.location\", \"address_components\"] }}`. Consult the Google Places API documentation for available fields.","message":"Incomplete Place Data (Missing Fields): By default, the Google Places API does not return all possible fields (e.g., `geometry`, `photos`, `address_components`). To access specific data like latitude/longitude, you must explicitly request these fields via the `options.fields` prop.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Go to Google Cloud Console, navigate to 'APIs & Services' -> 'Enabled APIs & services', and ensure 'Maps JavaScript API' is enabled for your project.","cause":"The Google Maps JavaScript API is not enabled for the provided API key in your Google Cloud project.","error":"Google Maps JavaScript API error: ApiNotActivatedMapError"},{"fix":"If manually loading the script, ensure `&libraries=places` is included in the script URL (e.g., `https://maps.googleapis.com/maps/api/js?key=YOUR_API_KEY&libraries=places`). If using the `apiKey` prop, ensure the 'Places API' is enabled in your Google Cloud Console.","cause":"The 'places' library, essential for autocomplete functionality, was not loaded with the Google Maps script.","error":"Google Maps JavaScript API error: PlacesLibraryNotLoaded"},{"fix":"Add `geometry` (or specific sub-fields like `geometry.location`) to the `options.fields` prop passed to the component or hook. For example: `options={{ fields: [\"formatted_address\", \"geometry\"] }}`.","cause":"Attempting to access `place.geometry.location.lat()` (or similar geometry properties) when the `geometry` field was not requested from the Google Places API.","error":"TypeError: Cannot read properties of undefined (reading 'lat')"},{"fix":"For `Autocomplete`: `import Autocomplete from 'react-google-autocomplete';`. For hooks: `import { usePlacesWidget } from 'react-google-autocomplete';`.","cause":"Incorrect import statement. `Autocomplete` is a default export, while hooks like `usePlacesWidget` and `usePlacesAutocompleteService` are named exports.","error":"Autocomplete is not a function / Cannot destructure property 'usePlacesWidget' of ... as it is undefined."}],"ecosystem":"npm"}