React Native

1. 1

   Install the package

   Required

   Install the PostHog React Native library and its dependencies:

   Expo

   bashCopy

   npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localization

   yarn

   bashCopy

   yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize
   
   # for iOS
   cd ios && pod install

   npm

   bashCopy

   npm i -s posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize
   
   # for iOS
   cd ios && pod install

2. 2

   Configure PostHog

   Required

   PostHog is most easily used via the PostHogProvider component. Wrap your app with the provider:

   App.tsx

   jsxCopy

   import { PostHogProvider } from 'posthog-react-native'
   
   export function MyApp() {
       return (
           <PostHogProvider
               apiKey="<ph_project_token>"
               options={
   
   
   
   
   
   
   

3. 3

   Send events

   Recommended

   Once installed, PostHog will automatically start capturing events. You can also manually send events using the usePostHog hook:

   Component.tsx

   jsxCopy

   import { usePostHog } from 'posthog-react-native'
   
   function MyComponent() {
       const posthog = usePostHog()
   
       const handlePress = () => {
   
   
   
   
   
   
   

4. 4

   Set up exception autocapture

   Recommended

   Client-side configuration only

   Support for remote configuration in the error tracking settings (opens in a new tab) requires SDK version 4.35.0 or higher.

   You can autocapture exceptions by configuring the errorTracking when setting up PostHog:

   React Native

   jsxCopy

   export const posthog = new PostHog('<ph_project_token>', {
     errorTracking: {
   
   
   
   
   
   
   
   

5. 5

   Set up error boundaries

   Optional

   You can use the PostHogErrorBoundary component to capture rendering errors thrown by components:

   React Native

   jsxCopy

   import { PostHogProvider, PostHogErrorBoundary } from 'posthog-react-native'
   import { View, Text } from 'react-native'
   
   const App = () => {
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

6. 6

   Manually capture exceptions

   Optional

   You can manually capture exceptions using the captureException method:

   React Native

   jsxCopy

   try {
     // Your awesome code that may throw
     someRiskyOperation();
   } catch (error) {
     posthog.captureException(error)
   }

   This is helpful if you’ve built your own error handling logic or want to capture exceptions that are handled by your application code.

7. 7

   Future features

   Optional

   We currently don’t support the following features:

   • No automatic source map uploads on React Native web

   This will be added in a future release. We recommend you stay up to date with the latest version of the PostHog React Native SDK.

8. Verify error tracking

   Recommended

   Confirm events are being sent to PostHog

   Before proceeding, let’s make sure exception events are being captured and sent to PostHog. You should see events appear in the activity feed.

   

   Check for exceptions in PostHog (opens in a new tab)

9. 8

   Upload source maps & native symbols

   Required

   Great, you’re capturing exceptions! The next step is to upload source maps (for JavaScript stack traces) and native symbols (for native iOS/Android crash symbolication) so PostHog can generate accurate stack traces.

   Let’s continue to the next section.

   Upload source maps & native symbols (opens in a new tab)

iOS dependency resolution for native crash capture

The @posthog/react-native-plugin package supports CocoaPods, the hybrid CocoaPods and Swift Package Manager path, and React Native’s full Swift Package Manager integration. PostHog verifies the full path with an iOS-only React Native 0.87.1 app and React Native Community CLI 20.2.0. This path requires @posthog/react-native-plugin 2.4.0 or later, Xcode 16 or later, and an iOS 15.1 or later app deployment target.

See iOS dependency paths for the React Native native plugin (opens in a new tab) for the requirements and setup steps. This verification does not cover Expo or other React Native versions. Use CocoaPods or the hybrid path unless you validate full Swift Package Manager for your configuration.

Still have questions?

Ask PostHog AI

Was this page useful?

HelpfulCould be better

Configuration options:

Capturing native crashes

nativeCrashes captures native iOS and Android crashes that the JavaScript layer can’t see. Beyond the config above, it needs:

1. The optional native plugin installed — npx expo install @posthog/react-native-plugin (Expo) or npm i @posthog/react-native-plugin (bare React Native). If it’s missing, native capture is a no-op and your JS-level autocapture is unaffected.
2. Your project’s Enable exception autocapture setting enabled in error tracking settings (opens in a new tab) — the same server-side setting that gates JavaScript autocapture.
3. Native debug symbols uploaded at build time, so crash stack traces are readable. See native crash symbolication (opens in a new tab).

Duplicate errors with console capture

If you have both PostHogErrorBoundary and console capture enabled in your errorTracking config, render errors will be captured twice. This is because React logs all errors to the console by default. To avoid this, set console: [] on errorTracking.autocapture (for example, errorTracking: { autocapture: { console: [] } }) when using PostHogErrorBoundary.

Dev mode behavior

In development mode, React propagates all errors to the global error handler even when they are caught by an error boundary. This means you may see errors reported twice in dev builds. This is expected React behavior and does not occur in production builds.