feat(clerk-js,shared,ui): Add phoneNumberCountryCode and preferredSignInIdentifier

nikosdouvlis · nikosdouvlis · commit 495ce1800421 · 2026-03-29T14:51:54.000+03:00
Adds two new features to the SignIn component:

- `phoneNumberCountryCode` (in `initialValues`): Preselects the country
  in the phone dropdown using an ISO 3166 alpha-2 code, without pre-filling
  the phone number. Precedence: parsed phone &gt; defaultCountryIso &gt; geo-IP &gt; 'us'.

- `preferredSignInIdentifier` (in `appearance.options`): Selects which
  identifier type (email, phone, username) shows first without pre-filling
  a value. Falls back to default ordering when the identifier is not enabled.
diff --git a/.changeset/phone-country-preferred-identifier.md b/.changeset/phone-country-preferred-identifier.md
@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/ui': minor
+---
+
+Add `phoneNumberCountryCode` to `SignIn` component's `initialValues` prop for preselecting the phone dropdown country via ISO 3166 alpha-2 code. Add `preferredSignInIdentifier` to `appearance.options` for selecting which identifier type (email, phone, username) shows first without pre-filling a value.
diff --git a/packages/shared/src/internal/clerk-js/constants.ts b/packages/shared/src/internal/clerk-js/constants.ts
@@ -50,7 +50,7 @@ export const ERROR_CODES = {
   USER_DEACTIVATED: 'user_deactivated',
 } as const;
 
-export const SIGN_IN_INITIAL_VALUE_KEYS = ['email_address', 'phone_number', 'username'];
+export const SIGN_IN_INITIAL_VALUE_KEYS = ['email_address', 'phone_number', 'username', 'phone_number_country_code'];
 export const SIGN_UP_INITIAL_VALUE_KEYS = ['email_address', 'phone_number', 'username', 'first_name', 'last_name'];
 
 export const DEBOUNCE_MS = 350;
diff --git a/packages/shared/src/types/clerk.ts b/packages/shared/src/types/clerk.ts
@@ -1366,6 +1366,7 @@ export type SignInInitialValues = {
   emailAddress?: string;
   phoneNumber?: string;
   username?: string;
+  phoneNumberCountryCode?: string;
 };
 
 export type SignUpInitialValues = {
diff --git a/packages/ui/src/components/SignIn/SignInAlternativePhoneCodePhoneNumberCard.tsx b/packages/ui/src/components/SignIn/SignInAlternativePhoneCodePhoneNumberCard.tsx
@@ -1,4 +1,5 @@
 import type { PhoneCodeChannelData } from '@clerk/shared/types';
+import type { CountryIso } from '@/ui/elements/PhoneInput/countryCodeData';
 
 import { Card } from '@/ui/elements/Card';
 import { useCardState } from '@/ui/elements/contexts';
@@ -16,10 +17,11 @@ type SignUpAlternativePhoneCodePhoneNumberCardProps = {
   phoneNumberFormState: FormControlState<any>;
   onUseAnotherMethod: () => void;
   phoneCodeProvider: PhoneCodeChannelData;
+  defaultCountryIso?: CountryIso;
 };
 
 export const SignInAlternativePhoneCodePhoneNumberCard = (props: SignUpAlternativePhoneCodePhoneNumberCardProps) => {
-  const { handleSubmit, phoneNumberFormState, onUseAnotherMethod, phoneCodeProvider } = props;
+  const { handleSubmit, phoneNumberFormState, onUseAnotherMethod, phoneCodeProvider, defaultCountryIso } = props;
   const { providerToDisplayData, strategyToDisplayData } = useEnabledThirdPartyProviders();
   const provider = phoneCodeProvider.name;
   const channel = phoneCodeProvider.channel;
@@ -72,6 +74,7 @@ export const SignInAlternativePhoneCodePhoneNumberCard = (props: SignUpAlternati
               <Form.ControlRow elementId='phoneNumber'>
                 <Form.PhoneInput
                   {...phoneNumberFormState.props}
+                  defaultCountryIso={defaultCountryIso}
                   label={localizationKeys('signIn.start.alternativePhoneCodeProvider.label', { provider })}
                   isRequired
                   isOptional={false}
diff --git a/packages/ui/src/components/SignIn/SignInStart.tsx b/packages/ui/src/components/SignIn/SignInStart.tsx
@@ -10,6 +10,7 @@ import type {
   SignInCreateParams,
   SignInResource,
 } from '@clerk/shared/types';
+import type { CountryIso } from '@/ui/elements/PhoneInput/countryCodeData';
 import { isWebAuthnAutofillSupported, isWebAuthnSupported } from '@clerk/shared/webauthn';
 import { useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 
@@ -33,7 +34,7 @@ import {
   withRedirectToSignInTask,
 } from '../../common';
 import { useCoreSignIn, useEnvironment, useSignInContext } from '../../contexts';
-import { Col, descriptors, Flow, localizationKeys } from '../../customizables';
+import { Col, descriptors, Flow, localizationKeys, useAppearance } from '../../customizables';
 import { CaptchaElement } from '../../elements/CaptchaElement';
 import { useLoadingStatus } from '../../hooks';
 import { useSupportEmail } from '../../hooks/useSupportEmail';
@@ -88,6 +89,7 @@ function SignInStartInternal(): JSX.Element {
   const ctx = useSignInContext();
   const { afterSignInUrl, signUpUrl, waitlistUrl, isCombinedFlow, navigateOnSetActive } = ctx;
   const supportEmail = useSupportEmail();
+  const { parsedOptions } = useAppearance();
   const totalEnabledAuthMethods = useTotalEnabledAuthMethods();
   const identifierAttributes = useMemo<SignInStartIdentifier[]>(
     () => groupIdentifiers(userSettings.enabledFirstFactorIdentifiers),
@@ -103,13 +105,46 @@ function SignInStartInternal(): JSX.Element {
   const authenticateWithPasskey = useHandleAuthenticateWithPasskey(onSecondFactor);
   const isWebSupported = isWebAuthnSupported();
 
-  const onlyPhoneNumberInitialValueExists =
-    !!ctx.initialValues?.phoneNumber && !(ctx.initialValues.emailAddress || ctx.initialValues.username);
-  const shouldStartWithPhoneNumberIdentifier =
-    onlyPhoneNumberInitialValueExists && identifierAttributes.includes('phone_number');
-  const [identifierAttribute, setIdentifierAttribute] = useState<SignInStartIdentifier>(
-    shouldStartWithPhoneNumberIdentifier ? 'phone_number' : identifierAttributes[0] || '',
-  );
+  const resolveInitialIdentifier = (): SignInStartIdentifier => {
+    const iv = ctx.initialValues;
+
+    const mapToIdentifierAttribute = (key: string): SignInStartIdentifier | undefined => {
+      if (key === 'phoneNumber') {
+        return identifierAttributes.includes('phone_number') ? 'phone_number' : undefined;
+      }
+      if (key === 'emailAddress') {
+        if (identifierAttributes.includes('email_address')) return 'email_address';
+        if (identifierAttributes.includes('email_address_username')) return 'email_address_username';
+        return undefined;
+      }
+      if (key === 'username') {
+        if (identifierAttributes.includes('email_address_username')) return 'email_address_username';
+        if (identifierAttributes.includes('username')) return 'username';
+        return undefined;
+      }
+      return undefined;
+    };
+
+    const filledValues = [
+      iv?.emailAddress && 'emailAddress',
+      iv?.phoneNumber && 'phoneNumber',
+      iv?.username && 'username',
+    ].filter(Boolean) as string[];
+
+    if (filledValues.length === 1) {
+      const mapped = mapToIdentifierAttribute(filledValues[0]);
+      if (mapped) return mapped;
+    }
+
+    if (parsedOptions.preferredSignInIdentifier) {
+      const mapped = mapToIdentifierAttribute(parsedOptions.preferredSignInIdentifier);
+      if (mapped) return mapped;
+    }
+
+    return identifierAttributes[0] || '';
+  };
+
+  const [identifierAttribute, setIdentifierAttribute] = useState<SignInStartIdentifier>(resolveInitialIdentifier);
   const [hasSwitchedByAutofill, setHasSwitchedByAutofill] = useState(false);
 
   const organizationTicket = getClerkQueryParam('__clerk_ticket') || '';
@@ -596,6 +631,9 @@ function SignInStartInternal(): JSX.Element {
                           actionLabel={nextIdentifier?.action}
                           onActionClicked={switchToNextIdentifier}
                           {...identifierFieldProps}
+                          defaultCountryIso={
+                            ctx.initialValues?.phoneNumberCountryCode?.toLowerCase() as CountryIso | undefined
+                          }
                           autoFocus={shouldAutofocus}
                           autoComplete={isWebAuthnAutofillSupported ? 'webauthn' : undefined}
                           isLastAuthenticationStrategy={isIdentifierLastAuthenticationStrategy}
@@ -650,6 +688,7 @@ function SignInStartInternal(): JSX.Element {
           phoneNumberFormState={phoneIdentifierField}
           onUseAnotherMethod={onAlternativePhoneCodeUseAnotherMethod}
           phoneCodeProvider={alternativePhoneCodeProvider}
+          defaultCountryIso={ctx.initialValues?.phoneNumberCountryCode?.toLowerCase() as CountryIso | undefined}
         />
       )}
     </Flow.Part>
diff --git a/packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx b/packages/ui/src/components/SignIn/__tests__/SignInStart.test.tsx
@@ -479,6 +479,65 @@ describe('SignInStart', () => {
     });
   });
 
+  describe('preferredSignInIdentifier (appearance option)', () => {
+    it('selects phone_number tab when set to phoneNumber', async () => {
+      const { wrapper, props } = await createFixtures(f => {
+        f.withEmailAddress();
+        f.withPhoneNumber();
+      });
+      props.setProps({ appearance: { options: { preferredSignInIdentifier: 'phoneNumber' } } });
+
+      render(<SignInStart />, { wrapper });
+      screen.getByText(/phone number/i);
+    });
+
+    it('selects email_address tab when set to emailAddress', async () => {
+      const { wrapper, props } = await createFixtures(f => {
+        f.withEmailAddress();
+        f.withPhoneNumber();
+      });
+      props.setProps({ appearance: { options: { preferredSignInIdentifier: 'emailAddress' } } });
+
+      render(<SignInStart />, { wrapper });
+      screen.getByText(/email address/i);
+    });
+
+    it('is ignored when identifier is not enabled', async () => {
+      const { wrapper, props } = await createFixtures(f => {
+        f.withEmailAddress();
+      });
+      props.setProps({ appearance: { options: { preferredSignInIdentifier: 'phoneNumber' } } });
+
+      render(<SignInStart />, { wrapper });
+      screen.getByText(/email address/i);
+    });
+
+    it('single filled initialValues value takes precedence', async () => {
+      const { wrapper, props } = await createFixtures(f => {
+        f.withEmailAddress();
+        f.withPhoneNumber();
+      });
+      props.setProps({
+        initialValues: { phoneNumber: '+306911111111' },
+        appearance: { options: { preferredSignInIdentifier: 'emailAddress' } },
+      });
+
+      render(<SignInStart />, { wrapper });
+      screen.getByDisplayValue(/691 1111111/i);
+    });
+
+    it('username maps to email_address_username when both enabled', async () => {
+      const { wrapper, props } = await createFixtures(f => {
+        f.withEmailAddress();
+        f.withUsername();
+      });
+      props.setProps({ appearance: { options: { preferredSignInIdentifier: 'username' } } });
+
+      render(<SignInStart />, { wrapper });
+      screen.getByText(/email address or username/i);
+    });
+  });
+
   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/customizables/parseAppearance.ts b/packages/ui/src/customizables/parseAppearance.ts
@@ -17,7 +17,8 @@ import {
 
 export type ParsedElements = Elements[];
 export type ParsedInternalTheme = InternalTheme;
-export type ParsedOptions = Required<Options>;
+export type ParsedOptions = Required<Omit<Options, 'preferredSignInIdentifier'>> &
+  Pick<Options, 'preferredSignInIdentifier'>;
 export type ParsedCaptcha = Required<CaptchaAppearanceOptions>;
 
 type PublicAppearanceTopLevelKey = Exclude<
@@ -51,6 +52,7 @@ const defaultOptions: ParsedOptions = {
   shimmer: true,
   animations: true,
   unsafe_disableDevelopmentModeWarnings: false,
+  preferredSignInIdentifier: undefined,
 };
 
 const defaultCaptchaOptions: ParsedCaptcha = {
diff --git a/packages/ui/src/elements/FieldControl.tsx b/packages/ui/src/elements/FieldControl.tsx
@@ -25,6 +25,7 @@ import type { FormFeedbackProps } from './FormControl';
 import { FormFeedback } from './FormControl';
 import { InputGroup } from './InputGroup';
 import { PasswordInput } from './PasswordInput';
+import type { CountryIso } from './PhoneInput/countryCodeData';
 import { PhoneInput } from './PhoneInput';
 import { RadioItem, RadioLabel } from './RadioGroup';
 
@@ -168,7 +169,7 @@ const FieldFeedback = (props: Pick<FormFeedbackProps, 'elementDescriptors' | 'ce
   );
 };
 
-const PhoneInputElement = forwardRef<HTMLInputElement>((_, ref) => {
+const PhoneInputElement = forwardRef<HTMLInputElement, { defaultCountryIso?: CountryIso }>((props, ref) => {
   const { t } = useLocalizations();
   const formField = useFormField();
   const { placeholder, ...inputProps } = sanitizeInputProps(formField);
@@ -179,6 +180,7 @@ const PhoneInputElement = forwardRef<HTMLInputElement>((_, ref) => {
       elementDescriptor={descriptors.formFieldInput}
       elementId={descriptors.formFieldInput.setId(formField.fieldId)}
       {...inputProps}
+      defaultCountryIso={props.defaultCountryIso}
       feedbackType={formField.feedbackType}
       placeholder={t(placeholder)}
     />
diff --git a/packages/ui/src/elements/Form.tsx b/packages/ui/src/elements/Form.tsx
@@ -1,5 +1,6 @@
 import { createContextAndHook } from '@clerk/shared/react';
 import type { FieldId } from '@clerk/shared/types';
+import type { CountryIso } from './PhoneInput/countryCodeData';
 import type { PropsWithChildren } from 'react';
 import React, { forwardRef, useState } from 'react';
 
@@ -196,10 +197,11 @@ const PasswordInput = forwardRef<HTMLInputElement, CommonInputProps>((props, ref
   );
 });
 
-const PhoneInput = (props: CommonInputProps) => {
+const PhoneInput = (props: CommonInputProps & { defaultCountryIso?: CountryIso }) => {
+  const { defaultCountryIso, ...rest } = props;
   return (
-    <CommonInputWrapper {...props}>
-      <Field.PhoneInput />
+    <CommonInputWrapper {...rest}>
+      <Field.PhoneInput defaultCountryIso={defaultCountryIso} />
     </CommonInputWrapper>
   );
 };
diff --git a/packages/ui/src/elements/PhoneInput/__tests__/useFormattedPhoneNumber.test.ts b/packages/ui/src/elements/PhoneInput/__tests__/useFormattedPhoneNumber.test.ts
@@ -118,4 +118,62 @@ describe('useFormattedPhoneNumber', () => {
 
     unmount();
   });
+
+  it('defaultCountryIso is used when no phone number and no locationBasedCountryIso', () => {
+    const { result } = renderHook(() =>
+      useFormattedPhoneNumber({
+        initPhoneWithCode: '',
+        defaultCountryIso: 'gr',
+        locationBasedCountryIso: undefined,
+      }),
+    );
+
+    expect(result.current.iso).toBe('gr');
+  });
+
+  it('defaultCountryIso takes precedence over locationBasedCountryIso', () => {
+    const { result } = renderHook(() =>
+      useFormattedPhoneNumber({
+        initPhoneWithCode: '',
+        defaultCountryIso: 'de',
+        locationBasedCountryIso: 'fr',
+      }),
+    );
+
+    expect(result.current.iso).toBe('de');
+  });
+
+  it('parsed phone number takes precedence over defaultCountryIso', () => {
+    const { result } = renderHook(() =>
+      useFormattedPhoneNumber({
+        initPhoneWithCode: '+71111111111',
+        defaultCountryIso: 'gr',
+      }),
+    );
+
+    expect(result.current.iso).toBe('ru');
+  });
+
+  it('invalid defaultCountryIso falls back to locationBasedCountryIso', () => {
+    const { result } = renderHook(() =>
+      useFormattedPhoneNumber({
+        initPhoneWithCode: '',
+        defaultCountryIso: 'xx' as any,
+        locationBasedCountryIso: 'fr',
+      }),
+    );
+
+    expect(result.current.iso).toBe('fr');
+  });
+
+  it('invalid defaultCountryIso with no locationBasedCountryIso falls back to us', () => {
+    const { result } = renderHook(() =>
+      useFormattedPhoneNumber({
+        initPhoneWithCode: '',
+        defaultCountryIso: 'zz' as any,
+      }),
+    );
+
+    expect(result.current.iso).toBe('us');
+  });
 });
diff --git a/packages/ui/src/elements/PhoneInput/index.tsx b/packages/ui/src/elements/PhoneInput/index.tsx
@@ -23,15 +23,27 @@ const createSelectOption = (country: CountryEntry) => {
 
 const countryOptions = [...IsoToCountryMap.values()].map(createSelectOption);
 
-type PhoneInputProps = PropsOfComponent<typeof Input> & { locationBasedCountryIso?: CountryIso };
+type PhoneInputProps = PropsOfComponent<typeof Input> & {
+  locationBasedCountryIso?: CountryIso;
+  defaultCountryIso?: CountryIso;
+};
 
 const PhoneInputBase = forwardRef<HTMLInputElement, PhoneInputProps & { feedbackType?: FeedbackType }>((props, ref) => {
-  const { onChange: onChangeProp, value, locationBasedCountryIso, feedbackType, sx, ...rest } = props;
+  const {
+    onChange: onChangeProp,
+    value,
+    locationBasedCountryIso,
+    defaultCountryIso,
+    feedbackType,
+    sx,
+    ...rest
+  } = props;
   const phoneInputRef = useRef<HTMLInputElement>(null);
   const phoneInputBox = useRef<HTMLDivElement>(null);
   const { setNumber, setIso, setNumberAndIso, numberWithCode, iso, formattedNumber } = useFormattedPhoneNumber({
     initPhoneWithCode: value as string,
     locationBasedCountryIso,
+    defaultCountryIso,
   });
 
   const callOnChangeProp = () => {
diff --git a/packages/ui/src/elements/PhoneInput/useFormattedPhoneNumber.ts b/packages/ui/src/elements/PhoneInput/useFormattedPhoneNumber.ts
diff --git a/packages/ui/src/internal/appearance.ts b/packages/ui/src/internal/appearance.ts
diff --git a/packages/ui/src/test/create-fixtures.tsx b/packages/ui/src/test/create-fixtures.tsx
