React Native

2

Configure PostHog

Required

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

App.tsx

PostHog AI

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 usePostHog hook:

Component.tsx

PostHog AI

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

PostHog AI

export const posthog = new PostHog('<ph_project_token>', {
  errorTracking: {
    autocapture: {
      uncaughtExceptions: true,
      unhandledRejections: true,
      console: ['error', 'warn'],
    },
  },
})

Configuration options:

5

Set up error boundaries

Optional

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

React Native

PostHog AI

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

6

Manually capture exceptions

Optional

You can manually capture exceptions using the captureException method:

React Native

PostHog AI

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 native Android and iOS exception capture
• No automatic source map uploads on React Native web

These features will be added in future releases. 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.

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

8

Upload source maps

Required

Great, you’re capturing exceptions! If you serve minified bundles, the next step is to upload source maps to generate accurate stack traces.

Let’s continue to the next section.

Upload source maps (opens in a new tab)