fix(ui): Add Forgot password? option to the SignInStart screen (#8733)

Ephem · web-flow · commit 6cf1078a4090 · 2026-06-10T08:57:30.000+02:00
diff --git a/.changeset/sign-in-start-forgot-password.md b/.changeset/sign-in-start-forgot-password.md
@@ -0,0 +1,5 @@
+---
+'@clerk/ui': patch
+---
+
+Add a "Forgot password?" action on the sign-in start page when the password field is shown. This improves the account recovery UX when strict user enumeration protection is enabled.
diff --git a/packages/ui/src/components/SignIn/SignInFactorOne.tsx b/packages/ui/src/components/SignIn/SignInFactorOne.tsx
@@ -13,7 +13,7 @@ import { localizationKeys } from '../../localization';
 import { useRouter } from '../../router';
 import type { AlternativeMethodsMode } from './AlternativeMethods';
 import { AlternativeMethods } from './AlternativeMethods';
-import { hasMultipleEnterpriseConnections } from './shared';
+import { hasMultipleEnterpriseConnections, SIGN_IN_RESET_PASSWORD_INTENT_PARAM } from './shared';
 import { SignInFactorOneAlternativePhoneCodeCard } from './SignInFactorOneAlternativePhoneCodeCard';
 import { SignInFactorOneEmailCodeCard } from './SignInFactorOneEmailCodeCard';
 import { SignInFactorOneEmailLinkCard } from './SignInFactorOneEmailLinkCard';
@@ -62,6 +62,18 @@ function determineAlternativeMethodsMode(
   return 'forgot';
 }
 
+function removeSignInResetPasswordIntentParam(): void {
+  if (typeof window === 'undefined') {
+    return;
+  }
+
+  const url = new URL(window.location.href);
+  if (url.searchParams.has(SIGN_IN_RESET_PASSWORD_INTENT_PARAM)) {
+    url.searchParams.delete(SIGN_IN_RESET_PASSWORD_INTENT_PARAM);
+    window.history.replaceState(window.history.state, '', url);
+  }
+}
+
 function SignInFactorOneInternal(): JSX.Element {
   const { __internal_setActiveInProgress } = useClerk();
   const signIn = useCoreSignIn();
@@ -97,13 +109,17 @@ function SignInFactorOneInternal(): JSX.Element {
     supportedFirstFactors,
   });
 
-  const [showAllStrategies, setShowAllStrategies] = React.useState<boolean>(
-    () => !currentFactor || !factorHasLocalStrategy(currentFactor),
-  );
-
   const resetPasswordFactor = useResetPasswordFactor();
+  const resetPasswordIntent = router.queryParams[SIGN_IN_RESET_PASSWORD_INTENT_PARAM] === 'true';
 
-  const [showForgotPasswordStrategies, setShowForgotPasswordStrategies] = React.useState(false);
+  const [showAllStrategies, setShowAllStrategies] = React.useState<boolean>(() => {
+    const defaultShow = !currentFactor || !factorHasLocalStrategy(currentFactor);
+    return defaultShow || (resetPasswordIntent && !resetPasswordFactor);
+  });
+
+  const [showForgotPasswordStrategies, setShowForgotPasswordStrategies] = React.useState(
+    () => resetPasswordIntent && !!resetPasswordFactor,
+  );
 
   const [passwordErrorCode, setPasswordErrorCode] = React.useState<PasswordErrorCode | null>(null);
 
@@ -159,10 +175,17 @@ function SignInFactorOneInternal(): JSX.Element {
     const canGoBack = factorHasLocalStrategy(currentFactor) && !passwordErrorCode;
 
     const toggle = showAllStrategies ? toggleAllStrategies : toggleForgotPasswordStrategies;
-    const backHandler = () => {
+    const leaveAlternativeMethods = () => {
+      // This search param only exists if the user clicked "Forgot password?" on the
+      // start page, it's a way to go directly to the password reset screen.
+      // If it does exist, we want to remove it on exit so refresh works correctly after.
+      removeSignInResetPasswordIntentParam();
+      toggle?.();
+    };
+    const backHandler: React.MouseEventHandler<Element> = () => {
       card.setError(undefined);
       setPasswordErrorCode(null);
-      toggle?.();
+      leaveAlternativeMethods();
     };
 
     const mode = determineAlternativeMethodsMode(showForgotPasswordStrategies, passwordErrorCode);
@@ -173,7 +196,7 @@ function SignInFactorOneInternal(): JSX.Element {
         onBackLinkClick={canGoBack ? backHandler : undefined}
         onFactorSelected={f => {
           selectFactor(f);
-          toggle?.();
+          leaveAlternativeMethods();
         }}
         currentFactor={currentFactor}
       />
diff --git a/packages/ui/src/components/SignIn/SignInStart.tsx b/packages/ui/src/components/SignIn/SignInStart.tsx
@@ -39,7 +39,11 @@ import { useSupportEmail } from '../../hooks/useSupportEmail';
 import { useTotalEnabledAuthMethods } from '../../hooks/useTotalEnabledAuthMethods';
 import { useRouter } from '../../router';
 import { handleCombinedFlowTransfer } from './handleCombinedFlowTransfer';
-import { hasMultipleEnterpriseConnections, useHandleAuthenticateWithPasskey } from './shared';
+import {
+  hasMultipleEnterpriseConnections,
+  SIGN_IN_RESET_PASSWORD_INTENT_PARAM,
+  useHandleAuthenticateWithPasskey,
+} from './shared';
 import { SignInAlternativePhoneCodePhoneNumberCard } from './SignInAlternativePhoneCodePhoneNumberCard';
 import { SignInSocialButtons } from './SignInSocialButtons';
 import {
@@ -347,7 +351,10 @@ function SignInStartInternal(): JSX.Element {
     });
   };
 
-  const signInWithFields = async (...fields: Array<FormControlState<string>>) => {
+  const signInWithFields = async (
+    fields: Array<FormControlState<string>>,
+    options?: { resetPasswordIntent?: boolean },
+  ) => {
     // If the user has already selected an alternative phone code provider, we use that.
     const preferredAlternativePhoneChannel =
       alternativePhoneCodeProvider?.channel ||
@@ -385,6 +392,11 @@ function SignInStartInternal(): JSX.Element {
           break;
         case 'needs_first_factor': {
           if (!hasOnlyEnterpriseSSOFirstFactors(res) || hasMultipleEnterpriseConnections(res.supportedFirstFactors)) {
+            if (options?.resetPasswordIntent) {
+              return navigate('factor-one', {
+                searchParams: new URLSearchParams({ [SIGN_IN_RESET_PASSWORD_INTENT_PARAM]: 'true' }),
+              });
+            }
             return navigate('factor-one');
           }
 
@@ -447,7 +459,7 @@ function SignInStartInternal(): JSX.Element {
     );
 
     if (instantPasswordError) {
-      await signInWithFields(identifierField);
+      await signInWithFields([identifierField]);
     } else if (sessionAlreadyExistsError) {
       await clerk.setActive({
         session: clerk.client.lastActiveSessionId,
@@ -514,7 +526,18 @@ function SignInStartInternal(): JSX.Element {
 
   const handleFirstPartySubmit = async (e: React.FormEvent<HTMLFormElement>) => {
     e.preventDefault();
-    return signInWithFields(identifierField, instantPasswordField);
+    return signInWithFields([identifierField, instantPasswordField]);
+  };
+
+  const handleForgotPasswordClick: React.MouseEventHandler = e => {
+    e.preventDefault();
+    // Surface the same native required-field validation as the Continue button
+    // when the identifier is missing
+    const form = e.currentTarget.closest('form');
+    if (form && !form.reportValidity()) {
+      return;
+    }
+    void signInWithFields([identifierField], { resetPasswordIntent: true });
   };
 
   const DynamicField = useMemo(() => {
@@ -600,7 +623,10 @@ function SignInStartInternal(): JSX.Element {
                           isLastAuthenticationStrategy={isIdentifierLastAuthenticationStrategy}
                         />
                       </Form.ControlRow>
-                      <InstantPasswordRow field={passwordBasedInstance ? instantPasswordField : undefined} />
+                      <InstantPasswordRow
+                        field={passwordBasedInstance ? instantPasswordField : undefined}
+                        onForgotPasswordClick={handleForgotPasswordClick}
+                      />
                     </Col>
                     <Col center>
                       <CaptchaElement />
@@ -663,7 +689,13 @@ const hasOnlyEnterpriseSSOFirstFactors = (signIn: SignInResource): boolean => {
   return signIn.supportedFirstFactors.every(ff => ff.strategy === 'enterprise_sso');
 };
 
-const InstantPasswordRow = ({ field }: { field?: FormControlState<'password'> }) => {
+const InstantPasswordRow = ({
+  field,
+  onForgotPasswordClick,
+}: {
+  field?: FormControlState<'password'>;
+  onForgotPasswordClick?: React.MouseEventHandler;
+}) => {
   const [autofilled, setAutofilled] = useState(false);
   const ref = useRef<HTMLInputElement>(null);
   const show = !!(autofilled || field?.value);
@@ -706,6 +738,8 @@ const InstantPasswordRow = ({ field }: { field?: FormControlState<'password'> })
     >
       <Form.PasswordInput
         {...field.props}
+        actionLabel={show ? localizationKeys('formFieldAction__forgotPassword') : undefined}
+        onActionClicked={show ? onForgotPasswordClick : undefined}
         ref={ref}
         tabIndex={show ? undefined : -1}
       />
diff --git a/packages/ui/src/components/SignIn/__tests__/SignInFactorOne.test.tsx b/packages/ui/src/components/SignIn/__tests__/SignInFactorOne.test.tsx
@@ -7,6 +7,7 @@ import { bindCreateFixtures } from '@/test/create-fixtures';
 import { act, mockWebAuthn, render, screen } from '@/test/utils';
 
 import { SignInFactorOne } from '../SignInFactorOne';
+import { SIGN_IN_RESET_PASSWORD_INTENT_PARAM } from '../shared';
 
 const { createFixtures } = bindCreateFixtures('SignIn');
 
@@ -142,6 +143,46 @@ describe('SignInFactorOne', () => {
         expect(screen.queryByText('Sign in with your password')).not.toBeInTheDocument();
       });
 
+      describe('reset password intent from start page', () => {
+        const { createFixtures: createFixturesWithResetIntent } = bindCreateFixtures('SignIn', {
+          router: { queryParams: { [SIGN_IN_RESET_PASSWORD_INTENT_PARAM]: 'true' } },
+        });
+
+        it('opens the forgot password screen when a reset factor exists', async () => {
+          const { wrapper } = await createFixturesWithResetIntent(f => {
+            f.withEmailAddress();
+            f.withPassword();
+            f.withPreferredSignInStrategy({ strategy: 'password' });
+            f.startSignInWithEmailAddress({
+              supportEmailCode: true,
+              supportPassword: true,
+              supportResetPassword: true,
+            });
+          });
+          render(<SignInFactorOne />, { wrapper });
+          await screen.findByText('Forgot Password?');
+          await screen.findByText('Reset your password');
+        });
+
+        it('opens use another method when no reset factor exists', async () => {
+          const email = 'test@clerk.com';
+          const { wrapper } = await createFixturesWithResetIntent(f => {
+            f.withEmailAddress();
+            f.withPassword();
+            f.withPreferredSignInStrategy({ strategy: 'password' });
+            f.startSignInWithEmailAddress({
+              supportEmailCode: true,
+              supportPassword: true,
+              supportResetPassword: false,
+              identifier: email,
+            });
+          });
+          render(<SignInFactorOne />, { wrapper });
+          await screen.findByText('Use another method');
+          await screen.findByText(`Email code to ${email}`);
+        });
+      });
+
       it('should render the Forgot Password alternative methods component when clicking on "Forgot password" (email)', async () => {
         const { wrapper, fixtures } = await createFixtures(f => {
           f.withEmailAddress();
diff --git a/packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx b/packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx
@@ -10,6 +10,7 @@ import { CardStateProvider } from '@/ui/elements/contexts';
 
 import { OptionsProvider } from '../../../contexts';
 import { AppearanceProvider } from '../../../customizables';
+import { SIGN_IN_RESET_PASSWORD_INTENT_PARAM } from '../shared';
 import { SignInStart } from '../SignInStart';
 
 const { createFixtures } = bindCreateFixtures('SignIn');
@@ -479,6 +480,47 @@ describe('SignInStart', () => {
     });
   });
 
+  describe('Forgot password on instant password field', () => {
+    it('navigates to factor-one with reset intent when clicking Forgot password', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withEmailAddress();
+        f.withPassword({ required: true });
+      });
+      fixtures.signIn.create.mockReturnValueOnce(Promise.resolve({ status: 'needs_first_factor' } as SignInResource));
+      const { userEvent, container } = render(<SignInStart />, { wrapper });
+
+      await userEvent.type(screen.getByLabelText(/email address/i), 'hello@clerk.com');
+      const instantPasswordField = container.querySelector('#password-field') as Element;
+      fireEvent.change(instantPasswordField, { target: { value: 'some-password' } });
+
+      await userEvent.click(screen.getByText(/Forgot password/i));
+
+      await waitFor(() => {
+        expect(fixtures.signIn.create).toHaveBeenCalledWith({
+          identifier: 'hello@clerk.com',
+        });
+        expect(fixtures.router.navigate).toHaveBeenCalledWith('factor-one', {
+          searchParams: new URLSearchParams({ [SIGN_IN_RESET_PASSWORD_INTENT_PARAM]: 'true' }),
+        });
+      });
+    });
+
+    it('does not call create when identifier is empty', async () => {
+      const { wrapper, fixtures } = await createFixtures(f => {
+        f.withEmailAddress();
+        f.withPassword({ required: true });
+      });
+      const { userEvent, container } = render(<SignInStart />, { wrapper });
+
+      const instantPasswordField = container.querySelector('#password-field') as Element;
+      fireEvent.change(instantPasswordField, { target: { value: 'some-password' } });
+
+      await userEvent.click(screen.getByText(/Forgot password/i));
+
+      expect(fixtures.signIn.create).not.toHaveBeenCalled();
+    });
+  });
+
   describe('Submitting form via instant password autofill', () => {
     const ERROR_CODES = ['strategy_for_user_invalid', 'form_password_incorrect', 'form_password_pwned'];
     ERROR_CODES.forEach(code => {
diff --git a/packages/ui/src/components/SignIn/shared.ts b/packages/ui/src/components/SignIn/shared.ts
@@ -11,6 +11,9 @@ import { handleError } from '@/ui/utils/errorHandler';
 import { useCoreSignIn, useSignInContext } from '../../contexts';
 import { useSupportEmail } from '../../hooks/useSupportEmail';
 
+/** Search param set when navigating from the start page "Forgot password?" action. */
+export const SIGN_IN_RESET_PASSWORD_INTENT_PARAM = '__clerk_reset_password';
+
 function useHandleAuthenticateWithPasskey(onSecondFactor: () => Promise<unknown>) {
   const card = useCardState();
   // @ts-expect-error -- private method for the time being
diff --git a/packages/ui/src/test/mock-helpers.ts b/packages/ui/src/test/mock-helpers.ts
@@ -87,7 +87,10 @@ export const mockClerkMethods = (clerk: LoadedClerk): DeepVitestMocked<LoadedCle
   return clerkAny as DeepVitestMocked<LoadedClerk>;
 };
 
-export const mockRouteContextValue = ({ queryString = '' }: Partial<DeepVitestMocked<RouteContextValue>>) => {
+export const mockRouteContextValue = ({
+  queryString = '',
+  queryParams,
+}: Partial<DeepVitestMocked<RouteContextValue>>) => {
   return {
     basePath: '',
     startPath: '',
@@ -96,7 +99,7 @@ export const mockRouteContextValue = ({ queryString = '' }: Partial<DeepVitestMo
     indexPath: '',
     currentPath: '',
     queryString,
-    queryParams: {},
+    queryParams: queryParams ?? {},
     getMatchData: vi.fn(),
     matches: vi.fn(),
     baseNavigate: vi.fn(),

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@clerk/ui': patch
 +---
++
 +Add a "Forgot password?" action on the sign-in start page when the password field is shown. This improves the account recovery UX when strict user enumeration protection is enabled.