Skip to content

README.md

Latest commit

 

History

History
251 lines (206 loc) · 8.34 KB

README.md

File metadata and controls

251 lines (206 loc) · 8.34 KB

react-native-streetview npm version

Google's StreetView component for React Native
(iOS and Android supported; Expo is supported — see Expo below)

Features

  • 🌐 Cross-platform Google Street View integration (iOS & Android)
  • 🎥 Customizable camera position and point of view (tilt, bearing, zoom)
  • 👆 Gesture controls for user interaction
  • 🔍 Configurable search radius to find nearby panoramas
  • 🏞️ Outdoor-only panorama option
  • 📊 Event callbacks for errors, location changes, and camera movements (POV)
  • ✅ Compatible with React Native 0.79+ and Fabric architecture
  • 📱 Expo: works with development builds and expo prebuild (native Google Maps / Street View setup still applies)

Preview

StreetView Demo

Installation

yarn add react-native-streetview
# or using npm
npm install --save react-native-streetview

Expo

This library ships native iOS and Android code, so use it with an Expo development build or a project using expo prebuild (not Expo Go). Install the package as above, then configure your Google Maps API keys the same way as in the iOS and Android sections (e.g. app.json / app.config.js plugins or config that set the native keys, depending on your setup).

API Key Setup

  1. Generate an API Key at https://console.developers.google.com/apis/credentials
  2. Make sure Google Maps API is enabled in the Google Cloud Console

iOS

  1. Install GoogleMaps SDK for iOS using CocoaPods:

  2. Add your API key to AppDelegate:

import GoogleMaps

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    GMSServices.provideAPIKey("YOUR-API-KEY")
    // ...existing code...
    return true
}

Android

  1. Install Google Play services:

  2. Add the API key to your app's Manifest file (android\app\src\main\AndroidManifest.xml):

    <application>
  <!-- You will only need to add this meta-data tag, but make sure it's a child of application -->
  <meta-data
    android:name="com.google.android.geo.API_KEY"
    android:value="YOUR-API-KEY"/>
</application>

Usage

Basic Implementation

import StreetView from 'react-native-streetview';
import { View, StyleSheet } from 'react-native';

const YourComponent = () => (
  <View style={styles.container}>
    <StreetView
      style={styles.streetView}
      allGesturesEnabled={true}
      coordinate={{
        latitude: 37.7749,
        longitude: -122.4194,
        radius: 50  // Search radius in meters
      }}
    />
  </View>
);

More Examples

With Camera Position (POV) 
<StreetView
  style={styles.streetView}
  coordinate={{
    latitude: 37.7749,
    longitude: -122.4194,
    radius: 50
  }}
  pov={{
    tilt: 30,     // Camera tilt angle in degrees (range: 0-90)
    bearing: 90,  // Camera compass direction (range: 0-360, where 0=North, 90=East)
    zoom: 1       // Camera zoom level (range: 0-5)
  }}
/>
Handling Events 
<StreetView
  style={styles.streetView}
  coordinate={{
    latitude: 37.7749,
    longitude: -122.4194,
    radius: 50
  }}
  onError={(errorEvent) => {
    // Access detailed error information
    const errorData = errorEvent.nativeEvent;
    console.log('Street View error:', errorData.message);
    // Access additional context for debugging
    if (errorData.outdoorOnly) {
      console.log('Try disabling outdoorOnly or increasing radius');
    }
    // For advanced debugging:
    console.log('Error details:', {
      location: `${errorData.latitude}, ${errorData.longitude}`,
      radius: errorData.radius,
      outdoorOnly: errorData.outdoorOnly
    });
  }}
  onPanoramaChange={(event) => {
    // When user navigates to a new panorama location
    const { position } = event.nativeEvent;
    const { panoId } = event.nativeEvent;
    console.log('Panorama changed to new location:', {
      latitude: position.latitude,
      longitude: position.longitude
    });
    // On iOS, may include additional Street View metadata
    if (panoId) {
      console.log('Panorama ID:', panoId);
    }
  }}
  onPovChange={(event) => {
    // When camera orientation changes
    const povData = event.nativeEvent;
    console.log('Camera view changed:');
    console.log('Bearing (direction):', povData.bearing);
    console.log('Tilt (angle):', povData.tilt);
    console.log('Zoom level:', povData.zoom);
    
    // * Only triggered when changes exceed threshold values
    // to avoid excessive updates during smooth camera movements
  }}
/>
Outdoor Only Panoramas 
<StreetView
  style={styles.streetView}
  coordinate={{
    latitude: 37.7749,
    longitude: -122.4194,
    radius: 100
  }}
  outdoorOnly={true}
/>

Props

Prop Type Default Description
Location
coordinate Object null Specify the latitude and longitude of the streetview location
coordinate.latitude Number 0 Latitude
coordinate.longitude Number 0 Longitude
coordinate.radius Number 50 Search radius in meters around the specified location. If no panorama is found at the exact coordinates, Google Street View will search for the closest panorama within this radius.
Display Options
outdoorOnly Boolean false When true, limits Street View searches to outdoor panoramas only
streetNamesHidden Boolean false Whether to hide street names overlay
Camera
pov Object null Camera point of view
pov.tilt Number 0 Camera tilt angle in degrees (0-90)
pov.bearing Number 0 Camera compass direction (0-360). 0 = north, 90 = east
pov.zoom Number 0 Camera zoom level (0-5)
Gesture Controls
allGesturesEnabled Boolean true Whether to enable all user gestures (panning, zooming, and navigation)
orientationGestures Boolean true Whether to enable panning gestures to change camera orientation
zoomGestures Boolean true Whether to enable pinch gestures to zoom the camera
navigationGestures Boolean true Whether to enable tap gestures to navigate between panoramas
navigationLinksHidden Boolean false Whether to hide the navigation links (iOS only)
Events
onError Function null Callback when panorama cannot be found or errors occur
onPanoramaChange Function null Callback when the panorama view changes to a new location
onPovChange Function null Callback when the Point of View (camera orientation) changes

Troubleshooting

No panoramas found

  • Ensure coordinates are in an area covered by Google Street View
  • Try increasing the search radius
  • Check if your API key has StreetView API enabled

Black screen issues

  • Verify your API key is correctly added to both platforms
  • For React Navigation users, add margins to the StreetView component as mentioned in the usage notes
  • Ensure the component has a proper size

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

About

This component was originally developed for Nester, a home rental application requiring Google Street View integration.

Contact & Support

For questions, issues, or feature requests, please contact:

License

MIT