native_address_autocomplete

A customizable Flutter address autocomplete TextField powered by native platform APIs.

Features

• No Google API key required.
• No Apple MapKit key required.
• No location permission required.
• iOS uses Apple MapKit MKLocalSearchCompleter.
• Android uses the platform Geocoder.
• Includes a TextField-style widget with a dropdown.
• Customize debounce, minimum characters, result limit, countries, dropdown height, item UI, and the full suggestions list.
• Shows a trailing loading indicator while searching.
• Optional clear button, error UI, keyboard navigation, and matched-text highlight.
• Resolve a selected suggestion into coordinates and address components.
• Optional FormField and external state controller.
• Use the system language by default, or pass a custom locale where supported.

Android Geocoder is best-effort and depends on the device's available geocoding service. It is useful for lightweight address suggestions, but it is not a full replacement for Google Places Autocomplete in delivery-critical flows. Some emulators, AOSP devices, or devices without a working geocoding backend may return few or no results.

Requirements

• Flutter 3.19.0 or newer
• Dart 3.3.0 or newer
• Android minSdk 24 or newer
• iOS 13.0 or newer
• Android uses Java 17-compatible builds
• iOS uses Swift 5.0-compatible builds

Usage

NativeAddressAutocompleteTextField(
  addressController: AddressAutocompleteController(),
  countries: const ['US', 'CA'],
  limit: 5,
  dropdownMaxHeight: 280,
  showLoadingIndicator: true,
  showClearButton: true,
  resolveOnSelected: true,
  useSystemLocale: true,
  // Android applies this locale to Geocoder. iOS MapKit follows system/app
  // language and ignores per-request locale overrides.
  locale: const Locale('fr', 'CA'),
  resultTypes: const {
    AddressResultType.address,
    AddressResultType.pointOfInterest,
  },
  decoration: const InputDecoration(
    labelText: 'Address',
    border: OutlineInputBorder(),
  ),
  itemBuilder: (context, suggestion, index) {
    return ListTile(
      title: Text(suggestion.primaryText),
      subtitle: suggestion.secondaryText == null
          ? null
          : Text(suggestion.secondaryText!),
    );
  },
  onSelected: (suggestion) {
    debugPrint(suggestion.fullText);
  },
  onError: (error) {
    debugPrint('Address autocomplete failed: $error');
  },
  onResolved: (address) {
    debugPrint(address.city);
    debugPrint('${address.latitude}, ${address.longitude}');
  },
  errorBuilder: (context, error) {
    return const Padding(
      padding: EdgeInsets.all(16),
      child: Text('Could not load suggestions.'),
    );
  },
)

Use it inside a Form:

final formKey = GlobalKey<FormState>();

Form(
  key: formKey,
  child: NativeAddressAutocompleteFormField(
    showClearButton: true,
    validator: (address) {
      return address == null ? 'Address required' : null;
    },
    onSaved: (address) {
      debugPrint(address?.fullText);
    },
  ),
)

Customize the trailing loading indicator:

NativeAddressAutocompleteTextField(
  loadingIndicatorBuilder: (context) {
    return const Padding(
      padding: EdgeInsets.all(12),
      child: CircularProgressIndicator.adaptive(strokeWidth: 2),
    );
  },
)

You can also use the client directly:

const autocomplete = NativeAddressAutocomplete();

final available = await autocomplete.isAvailable();

final suggestions = await autocomplete.suggest(
  '1600 Amph',
  countries: const ['US'],
  limit: 5,
  resultTypes: const {AddressResultType.address},
  localeTag: 'zh-Hant-TW',
);

final address = await autocomplete.resolve(suggestions.first);

debugPrint(address?.street);
debugPrint(address?.postalCode);

The dropdown opens below the text field. If there is not enough room, it uses the available height and scrolls its contents.

Platform notes

Error handling

Use errorBuilder to customize the dropdown error UI and onError to log or surface failures outside the widget.

NativeAddressAutocompleteTextField(
  onError: (error) {
    debugPrint('Address lookup failed: $error');
  },
  errorBuilder: (context, error) {
    return const Padding(
      padding: EdgeInsets.all(16),
      child: Text('Try again in a moment.'),
    );
  },
)