references/react-native.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
React Native Error Tracking installation
Canonical URL: https://posthog.com/docs/error-tracking/installation/react-native
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
- Install with the wizard
- Install the package
- Configure PostHog
- Send events
- Set up exception autocapture
- Set up error boundaries
- Manually capture exceptions
- Future features
- Verify error tracking
- Upload source maps & native symbols
- iOS dependency resolution for native crash capture
Install with the wizard
Run this command in your project directory to add PostHog to your React Native project. The wizard detects your framework, installs the SDK, and sets up your first events.
npx @posthog/wizard
Or set it up manually by following the rest of this guide.
-
1
Install the package
Required
Install the PostHog React Native library and its dependencies:
Expo
npx expo install posthog-react-native expo-file-system expo-application expo-device expo-localizationyarn
yarn add posthog-react-native @react-native-async-storage/async-storage react-native-device-info react-native-localize # for iOS cd ios && pod installnpm
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
Configure PostHog
Required
PostHog is most easily used via the
PostHogProvidercomponent. Wrap your app with the provider:App.tsx
import { PostHogProvider } from 'posthog-react-native' export function MyApp() { return ( <PostHogProvider apiKey="<ph_project_token>" options={{ host: "https://us.i.posthog.com", }} > <RestOfApp /> </PostHogProvider> ) } -
3
Send events
Recommended
Once installed, PostHog will automatically start capturing events. You can also manually send events using the
usePostHoghook:Component.tsx
import { usePostHog } from 'posthog-react-native' function MyComponent() { const posthog = usePostHog() const handlePress = () => { posthog.capture('button_pressed', { button_name: 'signup' }) } return <Button onPress={handlePress} title="Sign Up" /> } -
4
Set up exception autocapture
Recommended
Client-side configuration only
Support for remote configuration in the error tracking settings requires SDK version 4.35.0 or higher.
You can autocapture exceptions by configuring the
errorTrackingwhen setting up PostHog:React Native
export const posthog = new PostHog('<ph_project_token>', { errorTracking: { autocapture: { uncaughtExceptions: true, unhandledRejections: true, console: ['error', 'warn'], nativeCrashes: true, // native iOS/Android crashes (see below) }, }, })Configuration options:
| Option | Description | | --- | --- | |
uncaughtExceptions| Captures Uncaught exceptions (ReactNativeGlobal.ErrorUtils.setGlobalHandler) | |unhandledRejections| Captures Unhandled rejections (ReactNativeGlobal.onunhandledrejection) | |console| Captures console logs as errors according to the reportedLogLevel| |nativeCrashes| Captures native iOS/Android crashes. Requires@posthog/react-native-pluginand uploaded native symbols (see below) |Capturing native crashes
nativeCrashescaptures native iOS and Android crashes that the JavaScript layer can't see. Beyond the config above, it needs:- The optional native plugin installed —
npx expo install @posthog/react-native-plugin(Expo) ornpm 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. - Your project's Enable exception autocapture setting enabled in error tracking settings — the same server-side setting that gates JavaScript autocapture.
- Native debug symbols uploaded at build time, so crash stack traces are readable. See native crash symbolication.
- The optional native plugin installed —
-
5
Set up error boundaries
Optional
You can use the
PostHogErrorBoundarycomponent to capture rendering errors thrown by components:React Native
import { PostHogProvider, PostHogErrorBoundary } from 'posthog-react-native' import { View, Text } from 'react-native' const App = () => { return ( <PostHogProvider apiKey="<ph_project_token>"> <PostHogErrorBoundary fallback={YourFallbackComponent} additionalProperties={{ screen: "home" }} > <YourApp /> </PostHogErrorBoundary> </PostHogProvider> ) } const YourFallbackComponent = ({ error, componentStack }) => { return ( <View> <Text>Something went wrong!</Text> <Text>{error instanceof Error ? error.message : String(error)}</Text> </View> ) }Duplicate errors with console capture
If you have both
PostHogErrorBoundaryandconsolecapture enabled in yourerrorTrackingconfig, render errors will be captured twice. This is because React logs all errors to the console by default. To avoid this, setconsole: []onerrorTracking.autocapture(for example,errorTracking: { autocapture: { console: [] } }) when usingPostHogErrorBoundary.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.
-
6
Manually capture exceptions
Optional
You can manually capture exceptions using the
captureExceptionmethod:React Native
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
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.
-
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.
Activity feed with events
-
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.
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 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.