React component for the Geoapify Geocoder Autocomplete field
npm install @geoapify/react-geocoder-autocomplete
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.
!React Geocoder Autocomplete Screenshot
* 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.
``bash`
npm install @geoapify/geocoder-autocomplete @geoapify/react-geocoder-autocompleteor
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:
`tsx`
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:
`tsx`
{/ Your components go here /}
Tip: Store your API key in an environment variable and reference it as process.env.REACT_APP_GEOAPIFY_KEY for better maintainability.
Basic:
`tsx`
With events and common options:
`tsx`
lang="en"
limit={8}
addDetails={true}
placeSelect={onPlaceSelected}
suggestionsChange={onSuggestionsChange}
/>
`tsx
const onPlaceSelected = (feature) => {
console.log('Selected:', feature?.properties?.formatted);
};
const onSuggestionsChange = (list) => {
console.log('Suggestions:', list);
};
`
| @geoapify/react-geocoder-autocomplete | React Version |
| ------------------------------------- | -------------------- |
| 1.0.x – 1.1.x | >= 16.8.0 |
| 1.2.x – 1.3.x | >= 17.0.0 |
| 1.4.x – 1.5.x | >= 18.0.0 |
| 2.0.x – 2.2.x | >= 18.0.0, <= 19.x.x |
| 3.0.x | >= 19.0.0, <= 19.x.x |
> 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:
| Property | Direction | Description |
| --------------------- | --------- | --------------------------------------------------------------------------------- |
| placeholder | Prop | Sets the placeholder text for the input field. |type
| | Prop | Defines the type of location to search for — e.g. city, street, or amenity. |lang
| | Prop | Sets the language of suggestions and results. |limit
| | Prop | Limits the number of suggestions displayed. |debounceDelay
| | Prop | Adds a short delay before sending requests, improving performance. |filterByCountryCode
| | Prop | Restricts search results to selected countries. |biasByProximity
| | Prop | Prioritizes results near a specific location (latitude/longitude). |addDetails
| | Prop | Returns detailed information such as boundaries and place metadata. |skipIcons
| | Prop | Hides icons in the suggestion list for a minimal look. |placeSelect
| | Callback | Triggered when a user selects an address from suggestions. |suggestionsChange
| | Callback | Emits updated suggestions while typing. |onUserInput
| | Callback | Fires on each user input change. |
`tsx`
placeSelect={onPlaceSelected}
/>
`tsx`
const onPlaceSelected = (place) => {
console.log('Selected place:', place?.properties?.formatted);
};
Used properties:
placeholder, placeSelect
`tsx`
placeSelect={onPlaceSelected}
/>
Restricts suggestions to a list of countries using ISO country codes.
Used properties:
filterByCountryCode, placeSelect
`tsx`
placeSelect={onPlaceSelected}
/>
This configuration restricts search results to the Berlin area.
Used properties:
filterByRect, placeSelect
`tsx
import { useState, useEffect } from 'react';
const [userLocation, setUserLocation] = useState(null);
useEffect(() => {
navigator.geolocation.getCurrentPosition((pos) => {
setUserLocation({
lon: pos.coords.longitude,
lat: pos.coords.latitude
});
});
}, []);
`
`tsx`
placeSelect={onPlaceSelected}
/>
Prioritizes nearby results without strictly limiting the search area.
Used properties:
biasByProximity, placeSelect
`tsx`
suggestionsFilter={filterSuggestions}
/>
`tsx${value}, Berlin
const preprocessInput = (value) => {
return ;
};
const filterSuggestions = (suggestions) => {
return suggestions.filter(s => s.properties.result_type === 'street');
};
`
Used properties:
preprocessHook, suggestionsFilter
`tsx`
placeholder="Search for a city"
placeSelect={onPlaceSelected}
/>
Adds boundary or geometry data (where available) to the selected feature.
Used properties:
addDetails, placeSelect
`tsx`
showPlacesByCategoryList={true}
placesByCategoryFilter={{ categories: ['cafe', 'restaurant'] }}
onPlaceByCategorySelect={onPoiSelected}
/>
`tsx`
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
`tsx
import { useState } from 'react';
const [loading, setLoading] = useState(false);
{loading &&
Used properties:
onRequestStart, onRequestEnd$3
`tsx
onClear={onClear}
placeholder="Search address"
/>
``tsx
const onClear = (item) => {
console.log('Selection cleared:', item);
};
`Used properties:
onClear
$3
`tsx
filterByCountryCode={['DE']}
biasByProximity={{ lon: 13.405, lat: 52.52 }}
addDetails={true}
placeSelect={onPlaceSelected}
/>
`Combines multiple parameters — country restriction, local bias, and detailed output — for refined search results.
Used properties:
filterByCountryCode, biasByProximity, addDetails, placeSelect
Learn More
* 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.
Contributions and Support
We welcome feedback, bug reports, and feature suggestions to improve the library.
$3
If you'd like to contribute:
1. Fork the repository on GitHub.
2. Create a feature branch (
git checkout -b feature/your-feature-name`).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.