PlaceAutocomplete

A location search input with autocomplete suggestions powered by the Photon geocoding API, with location bias, bounding boxes and web-parity address formatting.

Edit on GitHubEditllms.txt

iOSAndroid

Preview PlaceAutocomplete on your device

Scan with Expo Go

iOS Android

Download Expo Go, then scan the QR code to preview native components.

Installation

pnpm dlx @docyrus/cli add @docyrus/rn-place-autocomplete

Usage

import { PlaceAutocomplete, type PlaceFeature } from '@/components/docyrus-native/place-autocomplete';

const [address, setAddress] = useState('');

<PlaceAutocomplete
  value={address}
  onChange={setAddress}
  onPlaceSelect={(feature: PlaceFeature) => {
    const [lon, lat] = feature.geometry.coordinates;
    saveLocation({ lat, lon });
  }}
/>

Uncontrolled

<PlaceAutocomplete defaultValue="Berlin" onPlaceSelect={handleSelect} />

Location bias & bounding box

<PlaceAutocomplete
  lang="tr"
  lat={41.0082}
  lon={28.9784}
  zoom={12}
  locationBiasScale={0.5}
  bbox={[28.5, 40.8, 29.5, 41.3]}
  onResultsChange={(results) => setCount(results.length)}
/>

Variants & sizes

<PlaceAutocomplete variant="outline" size="sm" />
<PlaceAutocomplete variant="ghost" size="lg" />

Behaviour

Typing sets the search query; the Photon request fires after debounceMs and is aborted when the query changes. Results are de-duplicated by osm_id.
Selecting a result writes formatAddress(properties) into the input (via onChange), clears the result list and calls onPlaceSelect(feature).
The result panel shows an error row, a "No places found for …" row, or the results (name / street + formatted address). It closes after a selection or a clear.
Address formatting (web parity): name, housenumber street (or street), city (falls back to locality), state (skipped when equal to city), country — duplicates removed.
An inline bbox={[…]} array is compared by value, so it never refires the search on re-render.

Translations

Key	English fallback
`ui.placeAutocomplete.searchPlaces`	`Search places...` (placeholder when `placeholder` is not set)
`ui.placeAutocomplete.clearSearch`	`Clear search` (clear button accessibility label)
`ui.placeAutocomplete.error`	`Error:`
`ui.placeAutocomplete.noPlacesFound`	`No places found for`
`ui.placeAutocomplete.unknown`	`Unknown` (result without a name or street)

API Reference

PlaceAutocompleteProps

Prop	Type	Default	Description
`value`	`string`	—	Current input value (controlled).
`defaultValue`	`string`	`''`	Initial input value (uncontrolled).
`onChange`	`(value: string) => void`	—	Called when the input value changes — typing, selecting a place, clearing.
`onValueChange`	`(value: string) => void`	—	Deprecated alias of `onChange` (called alongside it).
`onPlaceSelect`	`(feature: PlaceFeature) => void`	—	Called when a place is selected from the results.
`onResultsChange`	`(results: PlaceFeature[]) => void`	—	Called whenever the result list changes.
`debounceMs`	`number`	`300`	Debounce delay in milliseconds before searching.
`lang`	`string`	—	Preferred result language (`"en"`, `"de"`, `"fr"`…). Omitted → Photon default (local names).
`limit`	`number`	`5`	Maximum number of results.
`bbox`	`[number, number, number, number]`	—	Restricts results to `[minLon, minLat, maxLon, maxLat]`.
`lat`	`number`	—	Latitude to bias results toward (requires `lon`).
`lon`	`number`	—	Longitude to bias results toward (requires `lat`).
`zoom`	`number`	—	Zoom level for location biasing (higher = more local).
`locationBiasScale`	`number`	—	Strength of the location bias.
`variant`	`'default' \| 'outline' \| 'ghost'`	`'default'`	Visual style of the input.
`size`	`'sm' \| 'default' \| 'md' \| 'lg'`	`'default'`	Input size. `'md'` is an alias of `'default'`.
`placeholder`	`string`	`'Search places...'`	Placeholder text.
`disabled`	`boolean`	`false`	Disables the input.
`ref`	`Ref<TextInput>`	—	Ref to the underlying `TextInput`.
`className`	`string`	—	Additional classes for the container.
`inputClassName`	`string`	—	Additional classes for the `TextInput`.
`style`	`StyleProp<ViewStyle>`	—	Container style.
`...TextInputProps`	`TextInputProps`	—	Other `TextInput` props (`onFocus`, `onBlur`, `returnKeyType`, `testID`, …) are forwarded. `onFocus` / `onBlur` are chained.

PlaceSearchOptions

Field	Type	Description
`query`	`string`	Search text (address, place name or POI).
`lang`	`string`	Preferred language for results.
`limit`	`number`	Maximum number of results.
`bbox`	`[number, number, number, number]`	Bounding box `[minLon, minLat, maxLon, maxLat]`.
`lat`	`number`	Latitude for location bias.
`lon`	`number`	Longitude for location bias.
`zoom`	`number`	Zoom level for location bias.
`locationBiasScale`	`number`	Strength of the location bias.

PlaceFeature

Field	Type	Description
`type`	`'Feature'`	GeoJSON feature type
`geometry`	`{ type: 'Point'; coordinates: [number, number] }`	GeoJSON point geometry with `[longitude, latitude]`
`properties`	`PlaceFeatureProperties`	Address and metadata properties

PlaceFeatureProperties

Field	Type	Description
`osm_id`	`number`	OpenStreetMap ID
`osm_type`	`'N' \| 'W' \| 'R'`	OSM element type (Node, Way, Relation)
`osm_key`	`string`	OSM key (e.g. `place`, `amenity`)
`osm_value`	`string`	OSM value (e.g. `city`, `cafe`)
`type`	`string`	Photon result type (`house`, `street`, `city`, …)
`name`	`string?`	Place name
`housenumber`	`string?`	House number
`street`	`string?`	Street name
`locality`	`string?`	Locality (used when `city` is missing)
`district`	`string?`	District
`postcode`	`string?`	Postal code
`city`	`string?`	City name
`county`	`string?`	County
`state`	`string?`	State or province
`country`	`string?`	Country name
`countrycode`	`string?`	ISO country code
`extent`	`[number, number, number, number]?`	Bounding extent of the feature

Type Exports

Type	Description
`PlaceAutocompleteProps`	Props for the PlaceAutocomplete component
`PlaceAutocompleteVariant`	`'default' \| 'outline' \| 'ghost'`
`PlaceAutocompleteSize`	`'sm' \| 'default' \| 'md' \| 'lg'`
`PlaceSearchOptions`	Photon search options
`PlaceFeature`	GeoJSON feature returned by the geocoding API
`PlaceFeatureProperties`	Address properties of a place feature

PlaceAutocomplete

On this page