@julekgwa/react-native-places-autocomplete

react-native-places-autocomplete

A provider-agnostic React Native autocomplete component for searching addresses and places. Supports multiple built-in geocoding providers including OpenStreetMap (free), OpenCage, Google Places, Mapbox, LocationIQ, Geoapify, HERE, and TomTom, or use any custom API. Easy to integrate, fully customizable, and lightweight.

✨ Features

• 🌍 Built-in Providers - OpenStreetMap (free), OpenCage, Google Places, Mapbox, LocationIQ, Geoapify, HERE, TomTom
• 🔧 Provider Agnostic - Works with any geocoding API or use built-in providers
• 🎨 Fully Customizable - Complete theme and styling control
• 📱 React Native + Web Ready - Built specifically for React Native apps
• 🔍 Recent Searches - Built-in recent searches functionality
• ⚡ Debounced Requests - Optimized API calls with configurable debouncing
• 🎯 TypeScript Support - Full TypeScript support with type definitions
• 📦 Lightweight - Minimal dependencies
• 🔤 Query Options - Customize API requests with provider-specific parameters

📦 Installation

npm install @julekgwa/react-native-places-autocomplete

Additional Setup

Since the component uses SVG icons, you'll need to install react-native-svg:

For Expo projects:

expo install react-native-svg

For bare React Native projects, follow the react-native-svg installation guide.

🚀 Quick Start

Using Built-in Providers (Recommended)

The easiest way to get started is using one of the built-in providers:

import React from 'react';
import { LocationAutocomplete } from '@julekgwa/react-native-places-autocomplete';
import type { LocationSuggestion } from '@julekgwa/react-native-places-autocomplete';

const App = () => {
  const handleLocationSelect = (location: LocationSuggestion) => {
    console.log('Selected:', location);
  };

  return (
    <LocationAutocomplete
      // Use OpenStreetMap (completely free, no API key required)
      provider="openstreetmap"
      queryOptions={{
        countrycodes: "us,ca,gb", // Limit to specific countries
        limit: 8
      }}
      placeholder="Search for a location..."
      onLocationSelect={handleLocationSelect}
      showRecentSearches={true}
    />
  );
};

Using Built-in Providers with API Keys

// Mapbox example
<LocationAutocomplete
  provider="mapbox"
  providerConfig={{
    apiKey: "YOUR_MAPBOX_TOKEN"
  }}
  queryOptions={{
    country: "us",
    types: "place,address"
  }}
  onLocationSelect={handleLocationSelect}
/>

// Google Places example
<LocationAutocomplete
  provider="google"
  providerConfig={{
    apiKey: "YOUR_GOOGLE_API_KEY"
  }}
  queryOptions={{
    components: "country:us",
    types: "geocode"
  }}
  onLocationSelect={handleLocationSelect}
/>

📝 API Reference

Props

Prop	Type	Default	Description
fetchSuggestions	(query: string) => Promise<LocationSuggestion[]>	undefined	Function to fetch location suggestions (optional when using provider)
provider	LocationProvider	openstreetmap	Built-in provider: 'openstreetmap', 'mapbox', 'google', 'geoapify', 'locationiq'
providerConfig	ProviderConfig	{}	Configuration for built-in providers (API keys, base URLs)
queryOptions	QueryOptions	{limit: 10}	Provider-specific query parameters
onLocationSelect	(location: LocationSuggestion) => void	undefined	Callback when a location is selected
onQueryChange	(query: string) => void	undefined	Callback when search query changes
placeholder	string	"Search for a location..."	Input placeholder text
debounceMs	number	300	Debounce delay for API calls in milliseconds
showRecentSearches	boolean	true	Show recent searches when input is empty
recentSearches	string[]	[]	Array of recent search terms
onRecentSearchesChange	(searches: string[]) => void	undefined	Callback when recent searches update
maxRecentSearches	number	5	Maximum number of recent searches to keep
containerStyle	ViewStyle	undefined	Style for the main wrapper container
inputContainerStyle	ViewStyle	undefined	Style for the input container (with search icon, input, clear button)
inputStyle	TextStyle	undefined	Style for the TextInput field itself
suggestionStyle	ViewStyle	undefined	Style for individual suggestion items
textStyle	TextStyle	undefined	Style for text elements (titles, labels)
theme	DeepPartial<LocationAutocompleteTheme>	{}	Custom theme configuration
attribution	React.ComponentType | React.ReactElement	null	Attribution component for your provider

Documentation

You can view the live docs site at: https://juniusl.space/places-autocomplete

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

MIT © julekgwa

🙏 Acknowledgments

• Built with create-react-native-library
• Icons powered by react-native-svg
• Inspired by the React Native community