How to Add Address Autocomplete to an App

A user starts typing an incomplete address in an application and needs relevant suggestions before finishing the entire string. The Geoapify Address Autocomplete API accepts the current text and returns matching address or place suggestions.

The application decides when to request and display suggestions. When the user selects one, it receives a GeoJSON feature containing the formatted address, structured fields such as street, city, and postcode, and geographic coordinates. Geoapify provides a framework-independent JavaScript library plus Angular and React wrappers for implementing this interaction.

Plan the autocomplete experience

• When to request suggestions: Avoid calling the API for an empty value. Choose a minimum input length appropriate for the app—often two or three meaningful characters—and debounce typing before sending a request.
• Request lifecycle: Cancel or ignore superseded requests so a slower response for old text cannot replace newer suggestions. Show a subtle loading state without blocking typing.
• When to open the list: Show suggestions when the focused input has enough text and matching results are available. Do not open an empty dropdown before the user starts typing.
• When to close the list: Close it after selection, when the user presses Escape, or when focus moves outside the autocomplete. Define whether clicking outside preserves the typed text.
• Empty and error states: Distinguish “no matching addresses” from a network or authorization error, and provide a clear retry path when appropriate.
• Suggestion content: Show enough context to distinguish similar places—for example street and house number on the first line, then city, postcode, and country.
• Result count: Keep the list short enough to scan. Five to eight suggestions is usually more useful than a long result list.
• Search scope: Restrict results to supported countries or areas when locations elsewhere are invalid.
• Result ranking: Bias suggestions toward the user or current map view when nearby results should appear first.
• Address type: Decide whether the application accepts complete addresses, streets, cities, postcodes, or places, and configure the requested result type accordingly.
• Selection state: Store the selected feature separately from the visible input text. Text edited after selection is no longer a verified selection.
• Structured fields: Read fields such as housenumber, street, city, postcode, and country from the selected feature.
• Keyboard and accessibility: Support Arrow keys, Enter, Escape, visible focus, an associated input label, and appropriate combobox/listbox semantics. Announce loading, result counts, and selection changes to assistive technology.
• Mobile behavior: Use a touch-friendly input and suggestions, prevent the on-screen keyboard from hiding the selected row, and keep the list within the visible viewport.
• Location confirmation: For deliveries or entrances, let the user confirm the selected point on a map when precision matters.
• API-key safety: Browser keys are visible to users, so restrict them to allowed origins in Geoapify MyProjects.

Choose a library or the direct API

Use an NPM library when the application benefits from a ready-made input, suggestion list, keyboard interaction, debounce, selection events, themes, and lifecycle handling. Choose the package that matches the application framework.

Call the Address Autocomplete API directly when the application needs a completely custom interface, must combine suggestions with an existing design system, or performs autocomplete through a server-side proxy. With the direct API, the application is responsible for request timing, cancellation, rendering, keyboard behavior, accessibility, selection state, and cleanup.

Add address autocomplete with JavaScript

@geoapify/geocoder-autocomplete is a dependency-free autocomplete control that works with plain JavaScript and with map libraries such as Leaflet, MapLibre GL, and OpenLayers.

Use it for framework-independent web applications or as the base control inside a custom integration. The constructor receives the host element, API key, and search options. The library owns the input and suggestion-list interaction; the application listens for select to store the chosen feature.

npm install @geoapify/geocoder-autocomplete

<div id="autocomplete"></div>

import { GeocoderAutocomplete } from "@geoapify/geocoder-autocomplete";
import "@geoapify/geocoder-autocomplete/styles/minimal.css";

const autocomplete = new GeocoderAutocomplete(
  document.querySelector("#autocomplete"),
  "YOUR_API_KEY",
  {
    placeholder: "Enter an address",
    lang: "en",
    limit: 5
  }
);

autocomplete.on("select", (feature) => {
  if (!feature) return;

  const { housenumber, street, city, postcode, country, lat, lon } =
    feature.properties;

  console.log({ housenumber, street, city, postcode, country, lat, lon });
});

Import one packaged stylesheet or provide equivalent styles before displaying the control. Keep the complete selected feature rather than only its label so the application retains normalized address fields and coordinates. Call autocomplete.destroy() before permanently removing the host view to cancel active request lifecycles and clean up owned DOM listeners.

Add address autocomplete to Angular

@geoapify/angular-geocoder-autocomplete wraps the core library for Angular. Check its compatibility table before choosing a package version.

Use the Angular wrapper when the app should configure the API key through an Angular module and receive the selected GeoJSON feature through an Angular event binding. The wrapper handles creation and cleanup of the underlying autocomplete control with the component lifecycle.

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

Configure the module with your key, then add the component to a template:

<geoapify-geocoder-autocomplete
  placeholder="Enter an address"
  [limit]="5"
  (placeSelect)="onPlaceSelected($event)">
</geoapify-geocoder-autocomplete>

onPlaceSelected(feature: any): void {
  console.log(feature?.properties);
}

In a real form, save the selected feature or map its properties into the form model inside onPlaceSelected(). If the user edits the visible value afterward, clear or revalidate the stored selection so stale coordinates are not submitted.

Add address autocomplete to React

@geoapify/react-geocoder-autocomplete provides a React component and context for the API key. Check its compatibility table before choosing a package version.

Use the React wrapper when the app should provide its API key through context and handle the selected GeoJSON feature through a component callback. The context can be shared by multiple autocomplete fields beneath the same provider.

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

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

export function AddressField() {
  return (
    <GeoapifyContext apiKey="YOUR_API_KEY">
      <GeoapifyGeocoderAutocomplete
        placeholder="Enter an address"
        limit={5}
        placeSelect={(feature) => console.log(feature?.properties)}
      />
    </GeoapifyContext>
  );
}

Store the selected feature in component or form state inside placeSelect. Import a packaged stylesheet once at the application level, and keep the API-key context close enough to the autocomplete fields without recreating the provider on every render.

Custom implementation

For a custom implementation, you can use the geoapify/geocoder-autocomplete GitHub project as a base.

The project provides a working foundation for API requests, suggestion rendering, keyboard interaction, selection events, and component cleanup. Adapt its source and styles to the application's design and behavior instead of implementing the autocomplete interaction from scratch.

Implement address autocomplete with an AI coding agent

An AI coding agent can inspect the application’s framework and form architecture, build a custom autocomplete implementation, and connect selection data to existing state. Give it explicit UX, security, accessibility, and verification requirements instead of asking only to “add autocomplete.”

Example AI task:

Build a custom Geoapify address autocomplete for the existing address input in this application.

Requirements:
- Inspect the project first and follow its framework, form, styling, and testing conventions.
- Use https://github.com/geoapify/geocoder-autocomplete as the base for the custom implementation.
- Read the Geoapify API key from the project's existing environment/configuration system. Do not commit a key. Explain that browser keys must be restricted to allowed origins.
- Start requesting suggestions only after meaningful input and preserve the reference implementation's debounce and stale-request handling.
- Show suggestions only while the field is active and results are relevant. Support loading, no-results, error, outside-click, and Escape behavior.
- Preserve keyboard navigation and accessible labels and announcements.
- When the user selects a suggestion, store the complete feature and populate the existing structured address fields and coordinates.
- If the user edits the text after selection, clear or revalidate the stored feature.
- Apply the app's existing design tokens and responsive behavior; do not replace unrelated form or page code.
- Clean up requests, event listeners, and other autocomplete resources when the view is removed.
- Add or update focused tests for rendering, selection, edited-after-selection state, empty results, and cleanup.
- Run the relevant tests and build, then report changed files and any assumptions.

Review the generated change for API-key handling, accessible interaction, request cleanup, and correct mapping of the selected feature before accepting it.