The React Geocoder Autocomplete component integrates the core @geoapify/geocoder-autocomplete library into React. It provides an easy-to-use React wrapper for the Geoapify Geocoding Autocomplete API, allowing developers to add advanced, localized, and flexible address search functionality to their applications.

• Features
• Quick Start
• Compatibility
• Documentation
• Examples
• Learn More
• Contributions and Support

• Simple React integration with a ready-to-use component.
• Fast, responsive incremental search with built-in debounce.
• Localized suggestions with support for multiple languages and country filters.
• Flexible configuration: biasing, filtering, and bounding boxes.
• Customizable design: easily style or theme your component.
• Accessible with keyboard navigation and ARIA support.
• Rich results including coordinates, structured address, and metadata.
• Compatible with React 18–19.

You'll need a Geoapify API key to use the component.

1. Register for a free account at myprojects.geoapify.com.
2. Create a project to obtain your API key.
3. You can start for free — Geoapify offers a generous Freemium plan.

npm install @geoapify/geocoder-autocomplete @geoapify/react-geocoder-autocomplete # or yarn add @geoapify/geocoder-autocomplete @geoapify/react-geocoder-autocomplete

Get a Geoapify API key: https://myprojects.geoapify.com

Import the CSS style file from @geoapify/geocoder-autocomplete and the React components from @geoapify/react-geocoder-autocomplete:

import '@geoapify/geocoder-autocomplete/styles/minimal.css'; import { GeoapifyContext, GeoapifyGeocoderAutocomplete } from '@geoapify/react-geocoder-autocomplete';

Themes: minimal, round-borders, minimal-dark, round-borders-dark.

Wrap your component with the GeoapifyContext and provide your API key:

<GeoapifyContext apiKey="YOUR_GEOAPIFY_API_KEY"> {/* Your components go here */} </GeoapifyContext>

Tip: Store your API key in an environment variable and reference it as process.env.REACT_APP_GEOAPIFY_KEY for better maintainability.

Basic:

<GeoapifyGeocoderAutocomplete />

With events and common options:

<GeoapifyGeocoderAutocomplete placeholder="Search for an address" lang="en" limit={8} addDetails={true} placeSelect={onPlaceSelected} suggestionsChange={onSuggestionsChange} />

const onPlaceSelected = (feature) => { console.log('Selected:', feature?.properties?.formatted); }; const onSuggestionsChange = (list) => { console.log('Suggestions:', list); };

If you prefer to use the library directly without React bindings, check the Standalone Usage section.

Full documentation — including configuration options, detailed examples, and migration instructions — is available online at:

On the documentation site you'll find:

• A guided Quick Start to get the component running in minutes.
• A complete API Reference coverage of all props and callbacks.
• A dedicated Examples section with real-world scenarios (filters, biasing, category search, hooks).
• Guides for Standalone Usage of the underlying @geoapify/geocoder-autocomplete library.

The component includes many options for configuration and customization. Below are the most commonly used properties that cover typical address autocomplete use cases:

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete placeholder="Search for an address" placeSelect={onPlaceSelected} /> </GeoapifyContext>

const onPlaceSelected = (place) => { console.log('Selected place:', place?.properties?.formatted); };

Used properties: placeholder, placeSelect

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete filterByCountryCode={['us']} placeSelect={onPlaceSelected} /> </GeoapifyContext>

Restricts suggestions to a list of countries using ISO country codes.

Used properties: filterByCountryCode, placeSelect

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete filterByRect={{ lon1: 13.0884, lat1: 52.3383, lon2: 13.7611, lat2: 52.6755 }} placeSelect={onPlaceSelected} /> </GeoapifyContext>

This configuration restricts search results to the Berlin area.

Used properties: filterByRect, placeSelect

import { useState, useEffect } from 'react'; const [userLocation, setUserLocation] = useState(null); useEffect(() => { navigator.geolocation.getCurrentPosition((pos) => { setUserLocation({ lon: pos.coords.longitude, lat: pos.coords.latitude }); }); }, []);

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete biasByProximity={userLocation} placeSelect={onPlaceSelected} /> </GeoapifyContext>

Prioritizes nearby results without strictly limiting the search area.

Used properties: biasByProximity, placeSelect

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete preprocessHook={preprocessInput} suggestionsFilter={filterSuggestions} /> </GeoapifyContext>

const preprocessInput = (value) => { return `${value}, Berlin`; }; const filterSuggestions = (suggestions) => { return suggestions.filter(s => s.properties.result_type === 'street'); };

Used properties: preprocessHook, suggestionsFilter

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete addDetails={true} placeholder="Search for a city" placeSelect={onPlaceSelected} /> </GeoapifyContext>

Adds boundary or geometry data (where available) to the selected feature.

Used properties: addDetails, placeSelect

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete addCategorySearch={true} showPlacesByCategoryList={true} placesByCategoryFilter={{ categories: ['cafe', 'restaurant'] }} onPlaceByCategorySelect={onPoiSelected} /> </GeoapifyContext>

const onPoiSelected = ({ place, index }) => { console.log('Selected POI:', place.properties.name, 'at index', index); };

Enables category-based search for nearby Points of Interest (POIs) below the input field, filtered by category.

Used properties: addCategorySearch, showPlacesByCategoryList, placesByCategoryFilter, onPlaceByCategorySelect

import { useState } from 'react'; const [loading, setLoading] = useState(false); <div className="autocomplete-wrapper"> <GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete onRequestStart={() => setLoading(true)} onRequestEnd={() => setLoading(false)} placeSelect={onPlaceSelected} /> </GeoapifyContext> {loading && <div className="loading-spinner">Loading...</div>} </div>

Used properties: onRequestStart, onRequestEnd

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete onClear={onClear} placeholder="Search address" /> </GeoapifyContext>

const onClear = (item) => { console.log('Selection cleared:', item); };

Used properties: onClear

<GeoapifyContext apiKey="YOUR_API_KEY"> <GeoapifyGeocoderAutocomplete filterByCountryCode={['DE']} biasByProximity={{ lon: 13.405, lat: 52.52 }} addDetails={true} placeSelect={onPlaceSelected} /> </GeoapifyContext>

Combines multiple parameters — country restriction, local bias, and detailed output — for refined search results.

Used properties: filterByCountryCode, biasByProximity, addDetails, placeSelect

• Geoapify Geocoding API Docs
• Place Details API Docs
• Geoapify API Playground
• Geoapify Address Autocomplete Overview
• @geoapify/geocoder-autocomplete on npm — includes more live demos and examples.

We welcome feedback, bug reports, and feature suggestions to improve the library.

If you'd like to contribute:

1. Fork the repository on GitHub.
2. Create a feature branch (git checkout -b feature/your-feature-name).
3. Make your changes and ensure the code follows React and TypeScript best practices.
4. Submit a pull request with a clear description of your changes.

Before contributing, please review the existing issues and documentation to avoid duplicates.

If you encounter a bug or unexpected behavior, please open an issue on GitHub. When submitting an issue, include:

• A short description of the problem
• Steps to reproduce
• Expected vs. actual results
• React and package versions

• Visit the Geoapify Developer Portal for API documentation.
• Check the official documentation site for guides and examples.
• For general questions, contact the Geoapify support team via info@geoapify.com.