React Geocoder Autocomplete

The @geoapify/react-geocoder-autocomplete component serves as an interface to the @geoapify/geocoder-autocomplete library, seamlessly integrating its capabilities into React-based applications. This integration harnesses the power of the Geoapify Geocoding Autocomplete service for advanced address search functionality.

Address autocomplete is a feature that enhances user experience and accuracy when entering location-based information, particularly addresses. It's a technology often used in web and mobile applications to assist users in quickly and accurately inputting addresses by providing real-time suggestions as they type.

Installation

@geoapify/react-geocoder-autocomplete relies on @geoapify/geocoder-autocomplete as a peer dependency. To include both packages in your project, you can use the following commands:

Using npm:

npm install @geoapify/geocoder-autocomplete @geoapify/react-geocoder-autocomplete

Using Yarn:

yarn add @geoapify/geocoder-autocomplete @geoapify/react-geocoder-autocomplete

This ensures that both the React wrapper and the underlying geocoder-autocomplete library are correctly installed and compatible with each other in your project.

Compatibility Table

| @geoapify/react-geocoder-autocomplete | React | |----------------------------------------|-------| | 1.0.x | >= 16.8.0 | | 1.1.x | >= 16.8.0 | | 1.2.x | >= 17.0.0 | | 1.3.x | >= 17.0.0 | | 1.4.x | >= 18.0.0 | | 1.5.x | >= 18.0.0 | | 2.0.x | >= 18.0.0 |

This table provides compatibility information between different versions of @geoapify/react-geocoder-autocomplete and the required minimum version of React. Make sure to choose the appropriate version based on your React project's version.

Certainly, here's a complete "Getting Started" guide for using the @geoapify/react-geocoder-autocomplete library in your React project:

Getting Started

Geoapify Geocoder Autocomplete simplifies address search in your React applications. Follow these steps to get started:

Obtaining Your API Key

Before integrating the @geoapify/react-geocoder-autocomplete library into your project, you must acquire an API key from Geoapify. Here's a step-by-step guide:

1. Register for a Geoapify Account: If you don't already have a Geoapify account, visit Geoapify My Projects and sign up for a free account.

2. Create a New Project: After registering and logging in, create a new project in your Geoapify account.

3. Generate an API Key: Within your project settings, you can generate a new API key. Customize the key's settings according to your project's requirements. Once configured, generate the API key. Be sure to copy it because you'll need it to authenticate and use Geoapify services in your React project.

Integrate the Geocoder Autocomplete Component

To integrate the @geoapify/react-geocoder-autocomplete component into your React project, follow these steps:

1. Import Styles: Import the CSS style file from @geoapify/geocoder-autocomplete to ensure the control appears correctly. You can choose from various styles like minimal, round-borders, minimal-dark, or round-borders-dark, depending on your webpage's background color.

   import '@geoapify/geocoder-autocomplete/styles/minimal.css';

2. Add Geoapify Context and Provide API Key: Wrap your component with the GeoapifyContext and provide your Geoapify API key as a prop. This context will enable the component to authenticate and use Geoapify services.

   import { GeoapifyContext } from '@geoapify/react-geocoder-autocomplete';
   
   // Inside your component...
   <GeoapifyContext apiKey="YOUR_API_KEY_HERE">
     {/* Your Geoapify Geocoder Autocomplete components go here */}
   </GeoapifyContext>

   Replace "YOUR_API_KEY_HERE" with your actual Geoapify API key.

3. Add Geoapify Geocoder Autocomplete Component: You can add one or more instances of the GeoapifyGeocoderAutocomplete component within the GeoapifyContext. Customize the component by passing various props like placeholder, value, type, lang, and more, based on your specific requirements.

   Here's an example of using the component with different props and callback functions:

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

...
 <GeoapifyContext apiKey="YOUR_API_KEY">
  <GeoapifyGeocoderAutocomplete
    placeholder="Enter address here"
    value={value}
    type={type}
    lang={language}
    position={position}
    countryCodes={countryCodes}
    limit={limit}
    filterByCountryCode={filterByCountryCode}
    filterByCircle={filterByCircle}
    filterByRect={filterByRect}
    filterByPlace={filterByPlace}
    biasByCountryCode={biasByCountryCode}
    biasByCircle={biasByCircle}
    biasByRect={biasByRect}
    biasByProximity={biasByProximity}
    placeSelect={onPlaceSelect}
    suggestionsChange={onSuggestionChange}
  />
</GeoapifyContext>

Customize the props to meet your project's needs, and handle events like placeSelect and suggestionsChange by specifying callback functions as shown in the example.

Optionally, you can use preprocessing and postprocessing hooks, as well as suggestions filtering, by providing the respective functions as props to the GeoapifyGeocoderAutocomplete component. These functions allow you to modify user input and search results to fit your application's requirements.

By following these steps and configuring the GeoapifyGeocoderAutocomplete component with the necessary props and callbacks, you can seamlessly integrate address autocomplete functionality into your React project while customizing it to your specific needs.

API documentation

Here are the props for the GeoapifyGeocoderAutocomplete component:

| Prop | Type | Description | |--------------------------------|--------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | placeholder | string | Placeholder text for the input field. | | type | GeocoderAutocomplete.LocationType | The type of location to search for (e.g., 'city', 'postcode', 'street'). Default is 'city'. | | lang | GeocoderAutocomplete.SupportedLanguage | The language for search suggestions. Default is 'en'. | | limit | number | The maximum number of suggestions to display. Default is 5. | | value | string | The initial input value. | | filterByCountryCode | GeocoderAutocomplete.ByCountryCodeOptions | Filter suggestions by country code(s). | | filterByPlace | string | Filter suggestions by a specific place (e.g., 'New York'). | | filterByCircle | GeocoderAutocomplete.ByCircleOptions | Filter suggestions by a circular area. | | filterByRect | GeocoderAutocomplete.ByRectOptions | Filter suggestions by a rectangular area. | | biasByCountryCode | GeocoderAutocomplete.ByCountryCodeOptions | Bias suggestions by country code(s). | | biasByCircle | GeocoderAutocomplete.ByCircleOptions | Bias suggestions by a circular area. | | biasByRect | GeocoderAutocomplete.ByRectOptions | Bias suggestions by a rectangular area. | | biasByProximity | GeocoderAutocomplete.ByProximityOptions | Bias suggestions by proximity to a location. | | debounceDelay | number | Delay in milliseconds to wait for user input before triggering suggestions. Default is 100. | | skipIcons | boolean | Whether to skip displaying icons in suggestions. Default is false. | | addDetails | boolean | Whether to add detailed place information to suggestions. Default is false. | | skipSelectionOnArrowKey | boolean | Whether to skip selecting suggestions when using arrow keys. Default is false. | | allowNonVerifiedHouseNumber | boolean | Whether to allow non-verified house numbers in suggestions. Default is false. | | allowNonVerifiedStreet | boolean | Whether to allow non-verified streets in suggestions. Default is false. | | placeSelect | (value: GeoJSON.Feature) => void | Callback function when a place is selected. | | suggestionsChange | (values: GeoJSON.Feature[]) => void | Callback function when suggestions change. | | preprocessHook | (value: string) => string | Preprocessing hook for user input. | | postprocessHook | (feature: GeoJSON.Feature) => string | Postprocessing hook for selected suggestions. | | suggestionsFilter | (suggestions: GeoJSON.Feature[]) => any[] | Custom filter for suggestions. | | sendGeocoderRequestFunc | (value: string, geocoderAutocomplete: GeocoderAutocomplete) => Promise<GeoJSON.FeatureCollection> | Custom function to send geocoder requests. | | sendPlaceDetailsRequestFunc | (feature: GeoJSON.Feature, geocoderAutocomplete: GeocoderAutocomplete) => Promise<GeoJSON.Feature> | Custom function to send place details requests. | | onUserInput | (input: string) => void | Callback function when user input changes. | | onOpen | (opened: boolean) => void | Callback function when the suggestions dropdown opens. | | onClose | (opened: boolean) => void | Callback function when the suggestions dropdown closes. |

These props allow you to configure and customize the behavior of the GeoapifyGeocoderAutocomplete component in your React application.

You can apply multiple filters simultaneously, and the AND logic is used to combine these filters. Similarly, you can utilize multiple bias parameters concurrently, and the OR logic is employed to combine these biases.

The component does not have a dependency on @types/geojson. Nevertheless, you have the option to install it if you intend to work with GeoJSON types.

Explore More:

• Geoapify Maps and APIs
• Geoapify Address Autocomplete Playground
• Geoapify Address Autocomplete Docs