fix(ui): Fix HashRouter not responding to popup OAuth navigations (#7944)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: brkalow

.changeset/fix-hash-router-popup-oauth.md

@@ -0,0 +1,5 @@
+---
+'@clerk/clerk-js': patch
+---
+
+Fix HashRouter not responding to popup OAuth navigations by adding `pushstate`/`replacestate` to refresh events and suppressing the history observer during external navigation.

integration/templates/react-vite/src/main.tsx

@@ -7,6 +7,7 @@ import App from './App.tsx';
 import Protected from './protected';
 import SignIn from './sign-in';
 import SignInPopup from './sign-in-popup';
+import SignInHashPopup from './sign-in-hash-popup';
 import SignUp from './sign-up';
 import UserProfile from './user';
 import UserProfileCustom from './custom-user-profile';
@@ -66,6 +67,10 @@ const router = createBrowserRouter([
         path: '/sign-in-popup/*',
         element: <SignInPopup />,
       },
+      {
+        path: '/sign-in-hash-popup',
+        element: <SignInHashPopup />,
+      },
       {
         path: '/sign-up/*',
         element: <SignUp />,

integration/templates/react-vite/src/sign-in-hash-popup/index.tsx

@@ -0,0 +1,15 @@
+import { SignIn } from '@clerk/react';
+
+export default function Page() {
+  return (
+    <div>
+      <SignIn
+        routing='hash'
+        signUpUrl={'/sign-up'}
+        oauthFlow='popup'
+        fallbackRedirectUrl='/protected'
+        fallback={<>Loading sign in</>}
+      />
+    </div>
+  );
+}

integration/tests/oauth-flows.test.ts

@@ -238,6 +238,66 @@ testAgainstRunningApps({ withPattern: ['react.vite.withLegalConsent'] })(
   },
 );
 
+testAgainstRunningApps({ withPattern: ['react.vite.withLegalConsent'] })(
+  'oauth popup with hash-based routing @react',
+  ({ app }) => {
+    test.describe.configure({ mode: 'serial' });
+
+    let fakeUser: FakeUser;
+
+    test.beforeAll(async () => {
+      const client = createClerkClient({
+        secretKey: instanceKeys.get('oauth-provider').sk,
+        publishableKey: instanceKeys.get('oauth-provider').pk,
+      });
+      const users = createUserService(client);
+      fakeUser = users.createFakeUser({
+        withUsername: true,
+      });
+      await users.createBapiUser(fakeUser);
+    });
+
+    test.afterAll(async () => {
+      const u = createTestUtils({ app });
+      await fakeUser.deleteIfExists();
+      await u.services.users.deleteIfExists({ email: fakeUser.email });
+      await app.teardown();
+    });
+
+    test('popup OAuth navigates through sso-callback with hash-based routing', async ({ page, context }) => {
+      const u = createTestUtils({ app, page, context });
+
+      await u.page.goToRelative('/sign-in-hash-popup');
+      await u.page.waitForClerkJsLoaded();
+      await u.po.signIn.waitForMounted();
+
+      const popupPromise = context.waitForEvent('page');
+      await u.page.getByRole('button', { name: 'E2E OAuth Provider' }).click();
+      const popup = await popupPromise;
+      const popupUtils = createTestUtils({ app, page: popup, context });
+      await popupUtils.page.getByText('Sign in to oauth-provider').waitFor();
+
+      // Complete OAuth in the popup
+      await popupUtils.po.signIn.setIdentifier(fakeUser.email);
+      await popupUtils.po.signIn.continue();
+      await popupUtils.po.signIn.enterTestOtpCode();
+
+      // Because the user is new to the app and legal consent is required,
+      // the sign-up can't complete in the popup. The popup sends return_url
+      // back to the parent, which navigates to /sso-callback via pushState.
+      // With hash routing, the HashRouter must detect this pushState change
+      // to render the sso-callback route. hashchange does not fire for
+      // pushState, so the router needs pushstate/replacestate listeners.
+      await u.page.getByRole('heading', { name: 'Legal consent' }).waitFor();
+      await u.page.getByLabel(/I agree to the/).check();
+      await u.po.signIn.continue();
+
+      await u.page.getByText('SignedIn').waitFor();
+      await u.po.expect.toBeSignedIn();
+    });
+  },
+);
+
 testAgainstRunningApps({ withEnv: [appConfigs.envs.withLegalConsent] })(
   'oauth flows with legal consent @nextjs',
   ({ app }) => {

packages/ui/src/router/BaseRouter.tsx

@@ -232,10 +232,12 @@ export const BaseRouter = ({
     const isOutsideOfUIComponent = !toURL.pathname.startsWith('/' + basePath);
 
     if (isOutsideOfUIComponent || isCrossOrigin) {
-      const res = await clerkNavigate(toURL.href);
-      // TODO: Since we are closing the modal, why do we need to refresh ? wouldn't that unmount everything causing the state to refresh ?
-      refresh();
-      return res;
+      isNavigatingRef.current = true;
+      try {
+        return await clerkNavigate(toURL.href);
+      } finally {
+        isNavigatingRef.current = false;
+      }
     }
 
     // For internal navigation, preserve any query params

packages/ui/src/router/HashRouter.tsx

@@ -44,7 +44,7 @@ export const HashRouter = ({ preservedParams, children }: HashRouterProps): JSX.
       startPath={''}
       getQueryString={getQueryString}
       internalNavigate={internalNavigate}
-      refreshEvents={['popstate', 'hashchange']}
+      refreshEvents={['pushstate', 'replacestate', 'popstate', 'hashchange']}
       preservedParams={preservedParams}
     >
       {children}