Skip to main content

FAQ & Troubleshooting

Flags show up as two letters instead of a flag​

Country flags are emoji (regional indicator symbols). Web browsers and many Android devices have no font that renders them, so 🇧🇷 falls back to BR.

Bundle the TwemojiMozilla font that ships inside rn-country-select and recompile — step by step in the Installation guide.

note

Adding a font requires a native rebuild. Reloading the JS bundle is not enough.

If you would rather not ship a font, replace the emoji entirely with your own images:

<PhoneInput customFlag={(country) => <Image source={flags[country.cca2]} />} />

react-native-safe-area-context — do I really need it?​

Yes. It is a required peer dependency — the country selector modal uses it:

npm install react-native-safe-area-context
npx pod-install ios

You do not need to wrap your app in a SafeAreaProvider for the modal to work; it renders its own.

How do I get an E.164 number for my backend?​

internationalPhoneNumber is already E.164 — calling code plus national digits, no spaces, no punctuation:

const ref = useRef<IPhoneInputRef>(null);

ref.current?.nationalPhoneNumber;               // '11912345678'
ref.current?.nationalPhoneNumberFormatted;      // '11 91234 5678'
ref.current?.internationalPhoneNumber;          // '+5511912345678'  ← send this
ref.current?.internationalPhoneNumberFormatted; // '+55 11 91234 5678'

How do I block submit until the number is valid?​

Three ways, pick the one that matches your form — full walkthrough in the Validation guide.

// 1. imperative, at submit time
if (!ref.current?.isValidPhoneNumber) return;

// 2. reactive, drives a disabled button
<PhoneInput onValidationChange={(isValid) => setCanSubmit(isValid)} />

// 3. standalone (e.g. re-validating stored data)
import {isValidPhoneNumber, getCountryByCca2} from 'rn-international-phone-number';
isValidPhoneNumber('11912345678', getCountryByCca2('BR')!);

Why does the input start on Brazil?​

BR is the fallback when you pass neither defaultCountry nor defaultPhoneNumber, and also when the defaultPhoneNumber you passed matches no country. Fix it by being explicit:

<PhoneInput defaultCountry="US" />
<PhoneInput defaultPhoneNumber="+12505550199" /> // country inferred from the number

The country does not switch when I paste an international number​

It does — as long as the pasted text is E.164 (+ + calling code + number) and the value flows back into the component. If you keep the value in state, make sure onChangePhoneNumber writes to that same state:

<PhoneInput value={phone} onChangePhoneNumber={setPhone} />

Setting a number programmatically? Use the hook's setPhoneNumber, which routes through the same smart-paste pipeline:

const {setPhoneNumber} = usePhoneInput();
setPhoneNumber('+12025550123'); // switches to US and formats

Does it work with Expo / Expo Go?​

Yes. The library itself is pure JavaScript, and its native peer react-native-safe-area-context is part of the Expo Go runtime. The only thing Expo Go cannot do is load the flag font — for that you need a development build or a recompiled app.

Can I use my own UI instead of the built-in input?​

Yes — usePhoneInput is the same engine with no UI attached.

const {nationalPhoneNumberFormatted, onChangePhoneNumber, country} = usePhoneInput({
  defaultCountry: 'US',
});

Can I pass keyboardType, autoFocus, onBlur…?​

Yes. PhoneInput extends React Native's TextInputProps — every TextInput prop is forwarded, except value and onChangeText, which the component owns (use value + onChangePhoneNumber instead).

<PhoneInput autoFocus onBlur={handleBlur} returnKeyType="done" maxLength={20} />

Can I hide the modal / show only a few countries?​

<PhoneInput modalDisabled />                          // lock the country
<PhoneInput visibleCountries={['BR', 'PT', 'US']} />  // allow-list
<PhoneInput hiddenCountries={['RU']} />               // deny-list
<PhoneInput popularCountries={['BR', 'US']} />        // pinned to the top

Where did react-native-international-phone-number go?​

Same library, new package name: rn-international-phone-number.

:::danger The old package is not maintained The npm account that published react-native-international-phone-number is no longer under the author's control, so that package is frozen at v0.12.3 and gets no fixes or security patches from this project — and cannot be deprecated by the author.

Development continues only under rn-international-phone-number. Switch your dependency with the Migration guide. :::

How do I test the component?​

Every interactive element exposes a testID — see the Testing guide.

Still stuck?​

Open an issue with your React Native version, platform, and a minimal reproduction.