feat(ui): Wire preferredIdentifier into SignUp's getInitialActiveIdentifier

When both email and phone are in the same tier (both enabled and both
required, or both enabled and both optional), preferredIdentifier from
appearance.options now breaks the tie instead of hardcoding email-first.

Author: nikosdouvlis

packages/ui/src/components/SignUp/SignUpContinue.tsx

@@ -12,7 +12,7 @@ import { buildRequest, useFormControl } from '@/ui/utils/useFormControl';
 import { createUsernameError } from '@/ui/utils/usernameUtils';
 
 import { SignInContext, useCoreSignUp, useEnvironment, useSignUpContext } from '../../contexts';
-import { descriptors, Flex, Flow, localizationKeys, useLocalizations } from '../../customizables';
+import { descriptors, Flex, Flow, localizationKeys, useAppearance, useLocalizations } from '../../customizables';
 import { useRouter } from '../../router';
 import { SignUpForm } from './SignUpForm';
 import type { ActiveIdentifier } from './signUpFormHelpers';
@@ -44,8 +44,9 @@ function SignUpContinueInternal() {
   const isWithinSignInContext = !!React.useContext(SignInContext);
   const isCombinedFlow = !!(_isCombinedFlow && !!isWithinSignInContext);
   const isProgressiveSignUp = userSettings.signUp.progressive;
+  const { preferredIdentifier } = useAppearance().parsedOptions;
   const [activeCommIdentifierType, setActiveCommIdentifierType] = React.useState<ActiveIdentifier>(
-    getInitialActiveIdentifier(attributes, userSettings.signUp.progressive),
+    getInitialActiveIdentifier(attributes, userSettings.signUp.progressive, undefined, preferredIdentifier),
   );
   const ctx = useSignUpContext();
 

packages/ui/src/components/SignUp/SignUpStart.tsx

@@ -37,7 +37,7 @@ function SignUpStartInternal(): JSX.Element {
   const clerk = useClerk();
   const status = useLoadingStatus();
   const signUp = useCoreSignUp();
-  const { showOptionalFields } = useAppearance().parsedOptions;
+  const { showOptionalFields, preferredIdentifier } = useAppearance().parsedOptions;
   const { userSettings, authConfig } = useEnvironment();
   const { navigate } = useRouter();
   const { attributes } = userSettings;
@@ -47,16 +47,21 @@ function SignUpStartInternal(): JSX.Element {
   const { afterSignUpUrl, signInUrl, unsafeMetadata, navigateOnSetActive } = ctx;
   const isCombinedFlow = !!(ctx.isCombinedFlow && !!isWithinSignInContext);
   const [activeCommIdentifierType, setActiveCommIdentifierType] = React.useState<ActiveIdentifier>(() =>
-    getInitialActiveIdentifier(attributes, userSettings.signUp.progressive, {
-      phoneNumber: ctx.initialValues?.phoneNumber === null ? undefined : ctx.initialValues?.phoneNumber,
-      emailAddress: ctx.initialValues?.emailAddress === null ? undefined : ctx.initialValues?.emailAddress,
-      ...(isCombinedFlow
-        ? {
-            emailAddress: signUp.emailAddress,
-            phoneNumber: signUp.phoneNumber,
-          }
-        : {}),
-    }),
+    getInitialActiveIdentifier(
+      attributes,
+      userSettings.signUp.progressive,
+      {
+        phoneNumber: ctx.initialValues?.phoneNumber === null ? undefined : ctx.initialValues?.phoneNumber,
+        emailAddress: ctx.initialValues?.emailAddress === null ? undefined : ctx.initialValues?.emailAddress,
+        ...(isCombinedFlow
+          ? {
+              emailAddress: signUp.emailAddress,
+              phoneNumber: signUp.phoneNumber,
+            }
+          : {}),
+      },
+      preferredIdentifier,
+    ),
   );
   const { t, locale } = useLocalizations();
   const initialValues = ctx.initialValues || {};

packages/ui/src/components/SignUp/__tests__/signUpFormHelpers.test.ts

@@ -1047,4 +1047,71 @@ describe('getInitialActiveIdentifier()', () => {
       expect(getInitialActiveIdentifier(attributes, false)).toBe(null);
     });
   });
+
+  describe('respects preferredIdentifier on ties', () => {
+    it('returns phoneNumber in email-or-phone when preferredIdentifier is phoneNumber', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, false, true),
+        phone_number: createAttributeData('phone_number', true, false, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, false, undefined, 'phoneNumber')).toBe('phoneNumber');
+    });
+
+    it('returns emailAddress in email-or-phone when preferredIdentifier is emailAddress', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, false, true),
+        phone_number: createAttributeData('phone_number', true, false, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, false, undefined, 'emailAddress')).toBe('emailAddress');
+    });
+
+    it('returns phoneNumber when both are required and preferredIdentifier is phoneNumber', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, true, true),
+        phone_number: createAttributeData('phone_number', true, true, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, false, undefined, 'phoneNumber')).toBe('phoneNumber');
+    });
+
+    it('defaults to emailAddress in email-or-phone when no preferredIdentifier', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, false, true),
+        phone_number: createAttributeData('phone_number', true, false, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, false)).toBe('emailAddress');
+    });
+
+    it('ignores preferredIdentifier username since SignUp only has email/phone', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, false, true),
+        phone_number: createAttributeData('phone_number', true, false, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, false, undefined, 'username')).toBe('emailAddress');
+    });
+
+    it('initialValues take precedence over preferredIdentifier', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, false, true),
+        phone_number: createAttributeData('phone_number', true, false, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, false, { emailAddress: 'test@example.com' }, 'phoneNumber')).toBe(
+        'emailAddress',
+      );
+    });
+
+    it('returns phoneNumber in progressive signup email-or-phone with preferredIdentifier', () => {
+      const attributes = {
+        email_address: createAttributeData('email_address', true, false, true),
+        phone_number: createAttributeData('phone_number', true, false, true),
+      };
+
+      expect(getInitialActiveIdentifier(attributes, true, undefined, 'phoneNumber')).toBe('phoneNumber');
+    });
+  });
 });

packages/ui/src/components/SignUp/signUpFormHelpers.ts

@@ -107,6 +107,7 @@ export const getInitialActiveIdentifier = (
   attributes: Partial<Attributes>,
   isProgressiveSignUp: boolean,
   initialValues?: { phoneNumber?: string | null; emailAddress?: string | null },
+  preferredIdentifier?: 'emailAddress' | 'phoneNumber' | 'username',
 ): ActiveIdentifier => {
   if (initialValues?.emailAddress) {
     return 'emailAddress';
@@ -115,18 +116,29 @@ export const getInitialActiveIdentifier = (
     return 'phoneNumber';
   }
 
+  const preferred =
+    preferredIdentifier === 'emailAddress' || preferredIdentifier === 'phoneNumber' ? preferredIdentifier : undefined;
+
   if (emailOrPhone(attributes, isProgressiveSignUp)) {
-    // If we are in the case of Email OR Phone, email takes priority
-    return 'emailAddress';
+    return preferred ?? 'emailAddress';
   }
 
   const { email_address, phone_number } = attributes;
 
-  if (email_address?.enabled && isProgressiveSignUp ? email_address.required : email_address?.used_for_first_factor) {
+  const emailMatches =
+    email_address?.enabled && (isProgressiveSignUp ? email_address.required : email_address?.used_for_first_factor);
+  const phoneMatches =
+    phone_number?.enabled && (isProgressiveSignUp ? phone_number.required : phone_number?.used_for_first_factor);
+
+  if (emailMatches && phoneMatches) {
+    return preferred ?? 'emailAddress';
+  }
+
+  if (emailMatches) {
     return 'emailAddress';
   }
 
-  if (phone_number?.enabled && isProgressiveSignUp ? phone_number.required : phone_number?.used_for_first_factor) {
+  if (phoneMatches) {
     return 'phoneNumber';
   }