RUM Browser Monitoring - React integration

Overview

With the Datadog RUM React integration, resolve performance issues quickly in React components by:

• Debugging the root cause of performance bottlenecks, such as a slow server response time, render-blocking resource, or an error inside a component
• Automatically correlating web performance data with user journeys, HTTP calls, and logs
• Alerting your engineering teams when crucial web performance metrics (such as Core Web Vitals) fall below a threshold that results in a poor user experience

Monitor your React applications from end-to-end by:

• Tracking and visualizing user journeys across your entire stack
• Debugging the root cause of slow load times, which may be an issue with your React code, network performance, or underlying infrastructure
• Analyzing and contextualizing every user session with attributes such as user ID, email, name, and more
• Unifying full-stack monitoring in one platform for frontend and backend development teams

Setup

Start by setting up Datadog RUM in your React application. If you're creating a new RUM application in the Datadog App, select React as the application type. If you already have an existing RUM application, you can update its type to React instead. Once configured, the Datadog App will provide instructions for integrating the RUM-React plugin with the Browser SDK.

This integration supports React v18 or v19.

Error Tracking

To track React component rendering errors, choose one of the following approaches:

• An ErrorBoundary component (see React documentation) that catches errors and reports them to Datadog.
• The addReactError function from your own ErrorBoundary component.
• In React 19, the onCaughtError option from createRoot.

Do not report the same caught error from both an ErrorBoundary and onCaughtError, as this creates duplicate RUM error events.

ErrorBoundary usage

import { ErrorBoundary } from '@datadog/browser-rum-react'

function App() {
  return (
    <ErrorBoundary fallback={ErrorFallback}>
      <MyComponent />
    </ErrorBoundary>
  )
}

function ErrorFallback({ resetError, error }) {
  return (
    <p>
      Oops, something went wrong! <strong>{String(error)}</strong> <button onClick={resetError}>Retry</button>
    </p>
  )
}
Copy

Reporting React errors from your own ErrorBoundary

import { addReactError } from '@datadog/browser-rum-react'

class MyErrorBoundary extends React.Component {
  componentDidCatch(error, errorInfo) {
    addReactError(error, errorInfo)
  }

  render() {
    // ...
  }
}
Copy

React 19 createRoot Error Handling

React 19 introduced new error handling options for createRoot that can help capture errors more effectively. You can configure these options to work with Datadog RUM error tracking. See the createRoot documentation for more details.

The following example reports caught errors centrally through onCaughtError. Error boundaries are still needed to catch errors and render fallback UI, but they must not also call addReactError. If your application already uses the Datadog ErrorBoundary, or calls addReactError from a custom boundary's componentDidCatch, omit onCaughtError to avoid reporting caught errors twice.

import { createRoot } from 'react-dom/client'
import { addReactError } from '@datadog/browser-rum-react'

const container = document.getElementById('root')
const root = createRoot(container, {
  onUncaughtError: (error, errorInfo) => {
    // Report uncaught errors to Datadog
    addReactError(error, errorInfo)
    console.error('Uncaught error:', error, errorInfo)
  },
  onCaughtError: (error, errorInfo) => {
    // Report caught errors to Datadog
    addReactError(error, errorInfo)
    console.error('Caught error:', error, errorInfo)
  },
  onRecoverableError: (error, errorInfo) => {
    // Report recoverable errors to Datadog
    addReactError(error, errorInfo)
    console.warn('Recoverable error:', error, errorInfo)
  },
})

root.render(<App />)
Copy

These options provide comprehensive error coverage:

• onUncaughtError: Captures errors that would normally cause the app to crash
• onCaughtError: Captures errors that are caught by error boundaries
• onRecoverableError: Captures errors that React can recover from (like hydration mismatches)

React Router integration

React Router v6, v7, and v8 allow you to declare routes using the following methods:

• Create routers with createMemoryRouter, createHashRouter, or createBrowserRouter functions.
• Use the useRoutes hook.
• Use the Routes component.

To track route changes with the Datadog RUM Browser SDK, first initialize the reactPlugin with the router: true option, then replace those functions with their equivalent from the matching Datadog entry point. The version-agnostic entry point targets the latest supported React Router version:

import { createRoot } from 'react-dom/client'
import { RouterProvider } from 'react-router/dom'
import { datadogRum } from '@datadog/browser-rum'
import { reactPlugin } from '@datadog/browser-rum-react'
// Use "createBrowserRouter" from @datadog/browser-rum-react/react-router instead of react-router:
import { createBrowserRouter } from '@datadog/browser-rum-react/react-router'

datadogRum.init({
  // ...
  plugins: [reactPlugin({ router: true })],
})

const router = createBrowserRouter([
  {
    path: '/',
    element: <Root />,
    // ...
  },
])

createRoot(document.getElementById('root')).render(<RouterProvider router={router} />)
Copy

TanStack Router integration

TanStack Router v1.64.0 or later is a typesafe router for React. To track route changes with the Datadog RUM Browser SDK, first initialize the reactPlugin with the router: true option, then replace createRouter from @tanstack/react-router with its equivalent from @datadog/browser-rum-react/tanstack-router. Example:

import { createRoot } from 'react-dom/client'
import { RouterProvider } from '@tanstack/react-router'
import { datadogRum } from '@datadog/browser-rum'
import { reactPlugin } from '@datadog/browser-rum-react'
// Use "createRouter" from @datadog/browser-rum-react/tanstack-router instead of @tanstack/react-router:
import { createRouter } from '@datadog/browser-rum-react/tanstack-router'

datadogRum.init({
  // ...
  plugins: [reactPlugin({ router: true })],
})

const router = createRouter({ routeTree })

createRoot(document.getElementById('root')).render(<RouterProvider router={router} />)
Copy

RUM creates a new view on every path change. The view name uses the route's fullPath template, so navigating to /posts/42 is reported as /posts/$postId. Catch-all (splat) segments are replaced with the matched path, so /files/$ with _splat = "path/to/file" becomes /files/path/to/file. Query string changes do not create a new view.

Go further with Datadog React integration

Traces

Connect your RUM and trace data to get a complete view of your application's performance. See Connect RUM and Traces.

Logs

To start forwarding your React application's logs to Datadog, see JavaScript Logs Collection.

Metrics

To generate custom metrics from your RUM application, see Generate Metrics.

Troubleshooting

Need help? Contact Datadog Support.

Further Reading

Additional helpful documentation, links, and articles:

• React Monitoring