# rn-place-autocomplete
URL: /docs/native/docyrus/place-autocomplete

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

## Installation

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

## Usage

```tsx
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

```tsx

```

### Location bias & bounding box

```tsx
<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

```tsx

```

## 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 |