### Features
- [x] π¨ Theme customization.
- [x] π± UI written natively.
- [x] πΊοΈ Location reverse-geocoding (coordinate -> address).
- [x] π Searchable (users can search for location).
- [x] π Device location.
- [x] βοΈ Fully configurable.
- [x] ποΈ Supporting Turbo Modules (New Arch) with backward compatibility.
- [x] β‘ Renders on top of the app (Blazing Fast).
- [x] π Well typed.
- [x] π¦ Significantly small package.
- [x] π No peer dependencies except React and React-Native [[1]](#extra).
### How is it working?
> This plugin is built only by create native page `UIViewController` for iOS or `Activity` for Android. and present the page in front of React Native Application without any special dependencies just native code
## Installation
```sh
npm install react-native-place-picker
# or
yarn add react-native-place-picker
# or
pnpm add react-native-place-picker
# or
bun add react-native-place-picker
```
### Expo
- You need to add `expo-dev-client` and run `expo run:ios` or `expo run:android`
> **Info** Expo managed app not supported π§
### iOS
- If you want to enable user current location button you have to add this to your `Info.plist`
```xml
NSLocationWhenInUseUsageDescription
YOUR_PURPOSE_HERE
```
### Android β οΈ
- Add to your `AndroidManifest.xml` you Google Map API Key or your application will crash
```xml
```
### Request
```js
import { pickPlace } from "react-native-place-picker";
pickPlace({
enableUserLocation: true,
enableGeocoding: true,
color: "#FF00FF",
// Range selection (optional)
enableRangeSelection: true,
initialRadius: 2000,
minRadius: 250,
maxRadius: 10000,
radiusColor: '#FF00FF33',
radiusStrokeColor: '#FF00FF',
radiusStrokeWidth: 2,
//...etc
})
.then(console.log)
.catch(console.log);
// or
pickPlace().then(console.log).catch(console.log);
```
### Result
```ts
{
/**
* @description Selected coordinate.
*/
coordinate: PlacePickerCoordinate;
/**
* @description Geocoded address for selected location.
* @if `enableGeocoding: true`
*/
address?: PlacePickerAddress;
/**
* @description Did cancel the place picker window without selecting.
*/
didCancel: boolean;
}
```
### PlacePickerOptions
| Property | Type | Description | Default |
| -------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------- |
| `presentationStyle` | `PlacePickerPresentationStyle` \| string | Presentation style of the place picker window. **iOS only** | `'fullscreen'` |
| `title` | `string` | The title of the place picker window. | `'Choose Place'` |
| `searchPlaceholder` | `string` | Placeholder for the search bar in the place picker window. | `'Search...'` |
| `color` | `string` | Primary color of the theme (map pin, shadow, etc.). | `'#FF0000'` |
| `contrastColor` | `string` | Contrast color for the primary color. | `'#FFFFFF'` |
| `locale` | `string` | Locale for the returned address. | `'en-US'` |
| `initialCoordinates` | `PlacePickerCoordinate` | Initial map position. | `{ latitude: 25.2048, longitude: 55.2708 }` |
| `enableGeocoding` | `boolean` | geocoding for the selected address. | `true` |
| `enableSearch` | `boolean` | search bar for searching specific positions. | `true` |
| `enableUserLocation` | `boolean` | current user position button. Requires setup. | `true` |
| `enableLargeTitle` | `boolean` | large navigation bar title of the UIViewController. **iOS only** | `true` |
| `rejectOnCancel` | `boolean` | Reject and return nothing if the user dismisses the window without selecting a place. | `true` |
| `enableRangeSelection` | `boolean` | Enable draggable radius selection overlay. | `false` |
| `initialRadius` | `number` | Initial radius in meters when range selection is enabled. | `1000` |
| `minRadius` | `number` | Minimum allowed radius in meters. | `100` |
| `maxRadius` | `number` | Maximum allowed radius in meters. | `10000` |
| `radiusColor` | `string` | Fill color of radius circle (falls back to `color` with alpha). | `''` |
| `radiusStrokeColor` | `string` | Stroke color of radius circle (falls back to `color`). | `''` |
| `radiusStrokeWidth` | `number` | Stroke width of radius circle in pixels. | `2` |
### PlacePickerPresentationStyle
| Enum Value | Description |
| ------------ | -------------------------------------- |
| `modal` | Presentation style as a modal window. |
| `fullscreen` | Presentation style in fullscreen mode. |
### PlacePickerAddress
| Property | Type | Description |
| ------------ | -------- | --------------------------- |
| `name` | `string` | Name of the location. |
| `streetName` | `string` | Street name of the address. |
| `city` | `string` | City of the address. |
| `state` | `string` | State of the address. |
| `zipCode` | `string` | Zip code of the address. |
| `country` | `string` | Country of the address. |
### PlacePickerCoordinate
| Property | Type | Description |
| ----------- | -------- | -------------------------- |
| `latitude` | `number` | Latitude of the location. |
| `longitude` | `number` | Longitude of the location. |
### PlacePickerResults
| Property | Type | Description |
| ------------ | ----------------------- | -------------------------------------------------------------- |
| `coordinate` | `PlacePickerCoordinate` | Selected coordinate. |
| `address` | `PlacePickerAddress` | Geocoded address for selected location (if `enableGeocoding`). |
| `didCancel` | `boolean` | Indicates if the place picker was canceled without selecting. |
| `radius` | `number` | Selected radius in meters (if range selection enabled). |
| `radiusCoordinates` | `{ center, bounds }` | Center and bounds of the selected area. |
## Contributing
See the [contributing guide](CONTRIBUTING.md) to learn how to contribute to the repository and the development workflow.
## License
MIT