remix-run · brophdawg11 · Nov 14, 2025
diff --git a/.changeset/small-flowers-drive.md b/.changeset/small-flowers-drive.md
@@ -0,0 +1,5 @@
+---
+"react-router": minor
+---
+
+Stabilize `<HydratedRouter onError>`/`<RouterProvider onError>`
diff --git a/integration/browser-entry-test.ts b/integration/browser-entry-test.ts
@@ -146,7 +146,7 @@ test("allows users to pass an onError function to HydratedRouter", async ({
             document,
             <StrictMode>
               <HydratedRouter
-                unstable_onError={(error, errorInfo) => {
+                onError={(error, errorInfo) => {
                   console.log(error.message, JSON.stringify(errorInfo))
                 }}
               />

diff --git a/packages/react-router/__tests__/dom/client-on-error-test.tsx b/packages/react-router/__tests__/dom/client-on-error-test.tsx
@@ -44,7 +44,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
     await waitFor(() => screen.getByText("lazy error!"));
 
@@ -74,7 +74,7 @@ describe(`handleError`, () => {
       },
     ]);
 
-    render(<RouterProvider router={router} unstable_onError={spy} />);
+    render(<RouterProvider router={router} onError={spy} />);
 
     await waitFor(() => screen.getByText("Error:middleware error!"));
 
@@ -102,7 +102,7 @@ describe(`handleError`, () => {
       },
     ]);
 
-    render(<RouterProvider router={router} unstable_onError={spy} />);
+    render(<RouterProvider router={router} onError={spy} />);
 
     await waitFor(() => screen.getByText("Error:loader error!"));
 
@@ -131,7 +131,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -166,7 +166,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -197,7 +197,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -228,7 +228,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() =>
@@ -262,7 +262,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.fetch("key", "0", "/fetch"));
@@ -291,7 +291,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() =>
@@ -326,7 +326,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -370,7 +370,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -418,7 +418,7 @@ describe(`handleError`, () => {
     }
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -472,7 +472,7 @@ describe(`handleError`, () => {
     }
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -526,7 +526,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));
@@ -576,7 +576,7 @@ describe(`handleError`, () => {
     ]);
 
     let { container } = render(
-      <RouterProvider router={router} unstable_onError={spy} />,
+      <RouterProvider router={router} onError={spy} />,
     );
 
     await act(() => router.navigate("/page"));

diff --git a/packages/react-router/lib/components.tsx b/packages/react-router/lib/components.tsx
@@ -347,13 +347,13 @@ export interface RouterProviderProps {
    * and is only present for render errors.
    *
    * ```tsx
-   * <RouterProvider unstable_onError=(error, errorInfo) => {
+   * <RouterProvider onError=(error, errorInfo) => {
    *   console.error(error, errorInfo);
    *   reportToErrorService(error, errorInfo);
    * }} />
    * ```
    */
-  unstable_onError?: unstable_ClientOnErrorFunction;
+  onError?: unstable_ClientOnErrorFunction;
 }
 
 function shallowDiff(a: any, b: any) {
@@ -376,7 +376,7 @@ function shallowDiff(a: any, b: any) {
 export function UNSTABLE_TransitionEnabledRouterProvider({
   router,
   flushSync: reactDomFlushSyncImpl,
-  unstable_onError,
+  onError,
 }: RouterProviderProps) {
   let fetcherData = React.useRef<Map<string, any>>(new Map());
   let [revalidating, startRevalidation] = React.useTransition();
@@ -420,9 +420,9 @@ export function UNSTABLE_TransitionEnabledRouterProvider({
       navigator,
       static: false,
       basename,
-      unstable_onError,
+      onError,
     }),
-    [router, navigator, basename, unstable_onError],
+    [router, navigator, basename, onError],
   );
 
   React.useLayoutEffect(() => {
@@ -481,7 +481,7 @@ export function UNSTABLE_TransitionEnabledRouterProvider({
                 routes={router.routes}
                 future={router.future}
                 state={state}
-                unstable_onError={unstable_onError}
+                onError={onError}
               />
             </Router>
             {/* </ViewTransitionContext.Provider> */}
@@ -520,14 +520,14 @@ export function UNSTABLE_TransitionEnabledRouterProvider({
  * @mode data
  * @param props Props
  * @param {RouterProviderProps.flushSync} props.flushSync n/a
- * @param {RouterProviderProps.unstable_onError} props.unstable_onError n/a
+ * @param {RouterProviderProps.onError} props.onError n/a
  * @param {RouterProviderProps.router} props.router n/a
  * @returns React element for the rendered router
  */
 export function RouterProvider({
   router,
   flushSync: reactDomFlushSyncImpl,
-  unstable_onError,
+  onError,
 }: RouterProviderProps): React.ReactElement {
   let [state, setStateImpl] = React.useState(router.state);
   let [pendingState, setPendingState] = React.useState<RouterState>();
@@ -546,10 +546,10 @@ export function RouterProvider({
     (newState: RouterState) => {
       setStateImpl((prevState) => {
         // Send loader/action errors through handleError
-        if (newState.errors && unstable_onError) {
+        if (newState.errors && onError) {
           Object.entries(newState.errors).forEach(([routeId, error]) => {
             if (prevState.errors?.[routeId] !== error) {
-              unstable_onError(error, {
+              onError(error, {
                 location: newState.location,
                 params: newState.matches[0]?.params ?? {},
               });
@@ -559,7 +559,7 @@ export function RouterProvider({
         return newState;
       });
     },
-    [unstable_onError],
+    [onError],
   );
 
   let setState = React.useCallback<RouterSubscriber>(
@@ -761,9 +761,9 @@ export function RouterProvider({
       navigator,
       static: false,
       basename,
-      unstable_onError,
+      onError,
     }),
-    [router, navigator, basename, unstable_onError],
+    [router, navigator, basename, onError],
   );
 
   // The fragment and {null} here are important!  We need them to keep React 18's
@@ -788,7 +788,7 @@ export function RouterProvider({
                   routes={router.routes}
                   future={router.future}
                   state={state}
-                  unstable_onError={unstable_onError}
+                  onError={onError}
                 />
               </Router>
             </ViewTransitionContext.Provider>
@@ -807,14 +807,14 @@ function DataRoutes({
   routes,
   future,
   state,
-  unstable_onError,
+  onError,
 }: {
   routes: DataRouteObject[];
   future: DataRouter["future"];
   state: RouterState;
-  unstable_onError: unstable_ClientOnErrorFunction | undefined;
+  onError: unstable_ClientOnErrorFunction | undefined;
 }): React.ReactElement | null {
-  return useRoutesImpl(routes, undefined, state, unstable_onError, future);
+  return useRoutesImpl(routes, undefined, state, onError, future);
 }
 
 /**
@@ -1614,10 +1614,10 @@ export function Await<Resolve>({
     (error: unknown, errorInfo?: React.ErrorInfo) => {
       if (
         dataRouterContext &&
-        dataRouterContext.unstable_onError &&
+        dataRouterContext.onError &&
         dataRouterStateContext
       ) {
-        dataRouterContext.unstable_onError(error, {
+        dataRouterContext.onError(error, {
           location: dataRouterStateContext.location,
           params: dataRouterStateContext.matches?.[0]?.params || {},
           errorInfo,

diff --git a/packages/react-router/lib/context.ts b/packages/react-router/lib/context.ts
@@ -91,7 +91,7 @@ export interface DataRouterContextObject
   extends Omit<NavigationContextObject, "future"> {
   router: Router;
   staticContext?: StaticHandlerContext;
-  unstable_onError?: unstable_ClientOnErrorFunction;
+  onError?: unstable_ClientOnErrorFunction;
 }
 
 export const DataRouterContext =

diff --git a/packages/react-router/lib/dom-export/hydrated-router.tsx b/packages/react-router/lib/dom-export/hydrated-router.tsx
@@ -291,13 +291,13 @@ export interface HydratedRouterProps {
    * and is only present for render errors.
    *
    * ```tsx
-   * <HydratedRouter unstable_onError={(error, errorInfo) => {
+   * <HydratedRouter onError={(error, errorInfo) => {
    *   console.error(error, errorInfo);
    *   reportToErrorService(error, errorInfo);
    * }} />
    * ```
    */
-  unstable_onError?: unstable_ClientOnErrorFunction;
+  onError?: unstable_ClientOnErrorFunction;
 }
 
 /**
@@ -309,7 +309,7 @@ export interface HydratedRouterProps {
  * @mode framework
  * @param props Props
  * @param {dom.HydratedRouterProps.getContext} props.getContext n/a
- * @param {dom.HydratedRouterProps.unstable_onError} props.unstable_onError n/a
+ * @param {dom.HydratedRouterProps.onError} props.onError n/a
  * @returns A React element that represents the hydrated application.
  */
 export function HydratedRouter(props: HydratedRouterProps) {
@@ -402,10 +402,7 @@ export function HydratedRouter(props: HydratedRouterProps) {
         }}
       >
         <RemixErrorBoundary location={location}>
-          <RouterProvider
-            router={router}
-            unstable_onError={props.unstable_onError}
-          />
+          <RouterProvider router={router} onError={props.onError} />
         </RemixErrorBoundary>
       </FrameworkContext.Provider>
       {/*

diff --git a/packages/react-router/lib/hooks.tsx b/packages/react-router/lib/hooks.tsx
@@ -754,7 +754,7 @@ export function useRoutesImpl(
   routes: RouteObject[],
   locationArg?: Partial<Location> | string,
   dataRouterState?: DataRouter["state"],
-  unstable_onError?: unstable_ClientOnErrorFunction,
+  onError?: unstable_ClientOnErrorFunction,
   future?: DataRouter["future"],
 ): React.ReactElement | null {
   invariant(
@@ -908,7 +908,7 @@ export function useRoutesImpl(
       ),
     parentMatches,
     dataRouterState,
-    unstable_onError,
+    onError,
     future,
   );
 
@@ -1103,7 +1103,7 @@ export function _renderMatches(
   matches: RouteMatch[] | null,
   parentMatches: RouteMatch[] = [],
   dataRouterState: DataRouter["state"] | null = null,
-  unstable_onError: unstable_ClientOnErrorFunction | null = null,
+  onErrorHandler: unstable_ClientOnErrorFunction | null = null,
   future: DataRouter["future"] | null = null,
 ): React.ReactElement | null {
   if (matches == null) {
@@ -1187,9 +1187,9 @@ export function _renderMatches(
   }
 
   let onError =
-    dataRouterState && unstable_onError
+    dataRouterState && onErrorHandler
       ? (error: unknown, errorInfo?: React.ErrorInfo) => {
-          unstable_onError(error, {
+          onErrorHandler(error, {
             location: dataRouterState.location,
             params: dataRouterState.matches?.[0]?.params ?? {},
             errorInfo,