@kaisarsofi/react-native-phone-input 1.0.0

package/src/index.tsx

@@ -0,0 +1,21 @@
+export {
+  COUNTRIES,
+  getCountryByCode,
+  groupCountriesByLetter,
+  sectionLetterFor,
+} from './countries';
+export type { Country, CountrySection } from './countries';
+export { Flag } from './Flag';
+export { PhoneInput } from './PhoneInput';
+export { CountryPicker } from './CountryPicker';
+export { LIGHT_PALETTE, DARK_PALETTE, usePhoneInputPalette } from './theme';
+export type { PhoneInputPalette, PhoneInputColorScheme } from './theme';
+export type {
+  PhoneInputProps,
+  PhoneInputRef,
+  PhoneInputValue,
+  PhoneInputTheme,
+  CountryPickerRenderItemInfo,
+  CountryDisplayMode,
+  CountryPickerStyles,
+} from './types';

package/src/safeArea.ts

@@ -0,0 +1,50 @@
+import { createContext, useContext, type Context } from 'react';
+
+export interface EdgeInsets {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+}
+
+type SafeAreaModule = {
+  SafeAreaInsetsContext?: Context<EdgeInsets | null>;
+};
+
+/**
+ * `react-native-safe-area-context` is an *optional* peer: this library ships no
+ * native modules, so it is never installed on our account. The guarded require
+ * is what makes that safe — Metro registers a `require` inside a try/catch as
+ * an optional dependency and emits a runtime throw instead of failing the
+ * build (`allowOptionalDependencies`, enabled by default in both
+ * `@expo/metro-config` and `@react-native/metro-config`). The catch also covers
+ * bundlers that hand the ESM build a scope with no `require` at all.
+ */
+let optionalModule: SafeAreaModule | null = null;
+try {
+  optionalModule = require('react-native-safe-area-context') as SafeAreaModule;
+} catch {
+  optionalModule = null;
+}
+
+const FallbackContext = createContext<EdgeInsets | null>(null);
+
+/**
+ * Deliberately the *context* rather than `useSafeAreaInsets()`: that hook
+ * throws when no `SafeAreaProvider` is mounted above it, and plenty of apps
+ * carry the package transitively (React Navigation depends on it) without a
+ * provider in scope. Reading the context degrades to `null` instead.
+ *
+ * Resolved once at module scope so the identity is stable, which keeps the
+ * `useContext` call below an unconditional, rules-of-hooks-safe one.
+ */
+const InsetsContext: Context<EdgeInsets | null> =
+  optionalModule?.SafeAreaInsetsContext ?? FallbackContext;
+
+/** The ambient safe-area insets, or null when unavailable. */
+export function useOptionalSafeAreaInsets(): EdgeInsets | null {
+  return useContext(InsetsContext);
+}
+
+/** Whether the optional peer resolved. Exported for diagnostics and tests. */
+export const hasSafeAreaContext = optionalModule?.SafeAreaInsetsContext != null;

package/src/theme.ts

@@ -0,0 +1,112 @@
+import { useColorScheme } from 'react-native';
+import { useMemo } from 'react';
+
+/** Which palette to render with. "system" follows the OS appearance. */
+export type PhoneInputColorScheme = 'light' | 'dark' | 'system';
+
+/**
+ * Every color the input and the country picker draw with. Both palettes are
+ * complete, so dark mode needs no configuration — pass nothing and the
+ * component follows the OS. Override individual tokens via the `palette`
+ * prop when you want the component to match your own design system.
+ */
+/**
+ * Note the split with `theme`: `theme` styles the text field alone (its fill,
+ * its borders, its text), while this palette covers the field's neutral
+ * defaults *and* the whole picker sheet. Keeping them separate is what lets a
+ * field sitting on a colored background go fully custom without erasing the
+ * picker's separators or A-Z index along with it.
+ */
+export interface PhoneInputPalette {
+  /** Picker page background */
+  background: string;
+  /** The text field's own fill */
+  inputBackground: string;
+  /** Raised surfaces: search box, section headers, close button, selected row */
+  surface: string;
+  /** Pressed state for those surfaces */
+  surfacePressed: string;
+  /** Hairline separators, the input border, the country/number divider */
+  border: string;
+  /** Primary text: the number, country names, the picker title */
+  text: string;
+  /** Secondary text: dial codes, section letters, the empty state */
+  textMuted: string;
+  placeholder: string;
+  /** Focus ring and the A–Z index */
+  accent: string;
+  /** Text drawn on top of `accent` */
+  accentContrast: string;
+  /** Border shown when the typed number is invalid */
+  danger: string;
+  /** A–Z index letter with no countries under it */
+  disabled: string;
+  /** The sheet's drag handle */
+  handle: string;
+  /** The letter bubble shown while scrubbing the A–Z index */
+  bubble: string;
+  bubbleText: string;
+}
+
+export const LIGHT_PALETTE: PhoneInputPalette = {
+  background: '#FFFFFF',
+  inputBackground: '#FFFFFF',
+  surface: '#F2F2F7',
+  surfacePressed: '#E5E5EA',
+  border: '#D1D1D6',
+  text: '#1C1C1E',
+  textMuted: '#8E8E93',
+  placeholder: '#8E8E93',
+  accent: '#007AFF',
+  accentContrast: '#FFFFFF',
+  danger: '#FF3B30',
+  disabled: '#C7C7CC',
+  handle: '#D1D1D6',
+  bubble: 'rgba(60,60,67,0.85)',
+  bubbleText: '#FFFFFF',
+};
+
+export const DARK_PALETTE: PhoneInputPalette = {
+  background: '#1C1C1E',
+  inputBackground: '#1C1C1E',
+  surface: '#2C2C2E',
+  surfacePressed: '#3A3A3C',
+  border: '#38383A',
+  text: '#FFFFFF',
+  textMuted: '#98989F',
+  placeholder: '#8E8E93',
+  accent: '#0A84FF',
+  accentContrast: '#FFFFFF',
+  danger: '#FF453A',
+  disabled: '#48484A',
+  handle: '#48484A',
+  bubble: 'rgba(120,120,128,0.9)',
+  bubbleText: '#FFFFFF',
+};
+
+/**
+ * Resolves the palette for the current appearance. `colorScheme` forces one;
+ * "system" (the default) follows the OS and re-renders when it changes.
+ */
+export function usePhoneInputPalette(
+  colorScheme: PhoneInputColorScheme = 'system',
+  overrides?: Partial<PhoneInputPalette>
+): PhoneInputPalette {
+  const systemScheme = useColorScheme();
+  const resolved =
+    colorScheme === 'system' ? (systemScheme ?? 'light') : colorScheme;
+
+  // Keyed on the overrides' contents rather than their identity, because
+  // callers naturally write `palette={{ ... }}` inline. A new object every
+  // render would give the palette a new identity every render, and the picker
+  // memoizes ~20 style objects and its whole row list on that identity —
+  // serializing a handful of color strings is far cheaper than losing those.
+  const overridesKey = overrides ? JSON.stringify(overrides) : '';
+
+  return useMemo(() => {
+    const base = resolved === 'dark' ? DARK_PALETTE : LIGHT_PALETTE;
+    return { ...base, ...overrides };
+    // `overrides` is intentionally tracked through `overridesKey`.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [resolved, overridesKey]);
+}

package/src/types.ts

@@ -0,0 +1,229 @@
+import type { CountryCode } from 'libphonenumber-js';
+import type {
+  StyleProp,
+  TextInputProps,
+  TextStyle,
+  ViewStyle,
+} from 'react-native';
+import type { Country } from './countries';
+import type { PhoneInputColorScheme, PhoneInputPalette } from './theme';
+
+export type { Country };
+export type { PhoneInputColorScheme, PhoneInputPalette };
+
+export interface PhoneInputValue {
+  /** Raw digits the user typed, national significant number, no dial code (e.g. "4155552671") */
+  nationalNumber: string;
+  /** ISO 3166-1 alpha-2 country selected (e.g. "US") */
+  country: CountryCode;
+  /**
+   * Calling code without "+" (e.g. "1"). For the 23 NANP territories that
+   * share "+1" (Jamaica, Bermuda, etc.) this includes the distinguishing area
+   * code (e.g. "1876") so the picker can tell them apart — use `e164`, not
+   * `dialCode` + `nationalNumber`, to reconstruct the full number.
+   */
+  dialCode: string;
+  /** Full E.164 formatted number if valid, e.g. "+14155552671" */
+  e164: string | null;
+  /**
+   * The number as an international string at every keystroke, valid or not
+   * (e.g. "+1415555" while typing). Equals `e164` once the number is valid,
+   * and "" while the field is empty. Built through libphonenumber-js, so
+   * unlike `dialCode` + `nationalNumber` it is always correct for the NANP
+   * territories that share "+1" — use this, not string concatenation, when
+   * you need a value to store on every change.
+   */
+  international: string;
+  /** Whether libphonenumber-js considers the number valid for the selected country */
+  isValid: boolean;
+}
+
+export interface PhoneInputRef {
+  focus: () => void;
+  blur: () => void;
+  isValid: () => boolean;
+  getValue: () => PhoneInputValue;
+}
+
+export interface CountryPickerRenderItemInfo {
+  item: Country;
+  isSelected: boolean;
+  onPress: () => void;
+}
+
+export interface PhoneInputTheme {
+  backgroundColor?: string;
+  borderColor?: string;
+  focusedBorderColor?: string;
+  errorBorderColor?: string;
+  textColor?: string;
+  placeholderColor?: string;
+  dialCodeColor?: string;
+  /** The rule between the country control and the number. Defaults to the
+   * palette's border color — set it explicitly when the field itself is
+   * borderless, so the divider does not disappear with the border. */
+  dividerColor?: string;
+  borderRadius?: number;
+  fontSize?: number;
+}
+
+/** What the country control (left of the input) shows. */
+export type CountryDisplayMode = 'flag' | 'code' | 'both';
+
+/**
+ * Per-element style overrides for the country picker modal, so every part of it
+ * can be fully re-skinned — not just colors via `theme`. Each slot is merged on
+ * top of the built-in style, so you only need to specify what you're changing.
+ */
+export interface CountryPickerStyles {
+  /** The modal's root view */
+  container?: StyleProp<ViewStyle>;
+  /** The block holding the title row and search box, ruled off from the list */
+  headerSection?: StyleProp<ViewStyle>;
+  /** Row containing the title and close button */
+  header?: StyleProp<ViewStyle>;
+  title?: StyleProp<TextStyle>;
+  closeButton?: StyleProp<ViewStyle>;
+  closeButtonText?: StyleProp<TextStyle>;
+  /** The search field's box — fill, border, height */
+  searchContainer?: StyleProp<ViewStyle>;
+  /** The search field's text input */
+  search?: StyleProp<TextStyle>;
+  /** A single country row */
+  row?: StyleProp<ViewStyle>;
+  /** Merged on top of `row` when that row is the selected country */
+  rowSelected?: StyleProp<ViewStyle>;
+  flag?: StyleProp<TextStyle>;
+  name?: StyleProp<TextStyle>;
+  dialCode?: StyleProp<TextStyle>;
+  /** The "A", "B", "C"... letter header above each section */
+  sectionHeader?: StyleProp<ViewStyle>;
+  sectionHeaderText?: StyleProp<TextStyle>;
+  /** A single letter in the right-edge alphabet index */
+  sidebarLetter?: StyleProp<TextStyle>;
+  /** Merged on top of `sidebarLetter` for the currently-active letter */
+  sidebarLetterActive?: StyleProp<TextStyle>;
+}
+
+export interface PhoneInputProps extends Omit<
+  TextInputProps,
+  'value' | 'onChangeText' | 'onChange' | 'style'
+> {
+  /**
+   * ISO 3166-1 alpha-2 initial country, e.g. "US" (uncontrolled). Set this
+   * only when you want a *fixed* initial country regardless of the device —
+   * it always wins over locale detection. Leave it unset to prefer the
+   * device's locale region instead (see {@link fallbackCountry}).
+   */
+  defaultCountry?: CountryCode;
+  /**
+   * Initial country used only when `defaultCountry` is unset AND the
+   * device's locale region can't be resolved (or isn't in the current
+   * `countries`/`excludedCountries` list). Default: "US". Precedence for the
+   * initial country is: `defaultCountry` > device locale > `fallbackCountry`.
+   */
+  fallbackCountry?: CountryCode;
+  /** Controlled selected country. Falls back to internal state when omitted. */
+  country?: CountryCode;
+  /**
+   * Controlled value. Accepts either the national number on its own (digits,
+   * no dial code — e.g. "4155552671") or a full international number starting
+   * with "+" (e.g. "+14155552671"), in which case the selected country is
+   * derived from it. The international form lets a form store one string and
+   * hand it straight back, with no country state of its own; it is also what
+   * {@link onChangeInternational} emits. The selected country only changes
+   * when the calling code does, so picking a specific "+1" territory is not
+   * undone by the next keystroke.
+   */
+  value?: string;
+  /** Called with the composed value on every change */
+  onChangeText?: (value: PhoneInputValue) => void;
+  /**
+   * Called on every change with {@link PhoneInputValue.international} alone.
+   * Pairs with the international form of `value` so a form field can be wired
+   * up with just `value` and this callback.
+   */
+  onChangeInternational?: (value: string) => void;
+  /** Called only when the selected country changes */
+  onChangeCountry?: (country: Country) => void;
+  /** Restrict the picker to a subset of ISO codes */
+  countries?: CountryCode[];
+  /** Exclude specific ISO codes from the picker */
+  excludedCountries?: CountryCode[];
+  /** Disable the built-in libphonenumber-js validation styling/behavior */
+  disableValidation?: boolean;
+  /** Format the national number as the user types (default: true) */
+  autoFormat?: boolean;
+  /** Show a country control (flag/code) to the left of the input (default: true) */
+  showCountryPicker?: boolean;
+  /** What the country control shows: 'flag' | 'code' | 'both' (default: 'both') */
+  displayMode?: CountryDisplayMode;
+  /** Render a completely custom flag element instead of the built-in one */
+  renderFlag?: (country: Country) => React.ReactNode;
+  /** Render a fully custom row inside the country picker list */
+  renderCountryItem?: (info: CountryPickerRenderItemInfo) => React.ReactNode;
+  /** Placeholder for the picker search box */
+  searchPlaceholder?: string;
+  /** Hide the search box inside the country picker */
+  disableSearch?: boolean;
+  /**
+   * Group the picker list into A–Z sections with letter headers (default: true).
+   * Independent of {@link showAlphabetIndex} — either can be on without the other.
+   */
+  groupAlphabetically?: boolean;
+  /**
+   * Show an A–Z index sidebar on the right edge of the picker for tap/drag jumping
+   * (default: true). Works whether or not {@link groupAlphabetically} is on: with
+   * it off, the list stays flat but the index still jumps to the right country.
+   */
+  showAlphabetIndex?: boolean;
+  /**
+   * When the user types or pastes a number that starts with "+" and its calling
+   * code resolves to a country in the current list, auto-switch the selected
+   * country to match (e.g. pasting "+911234567890" selects India). Default: true.
+   */
+  autoDetectCountry?: boolean;
+
+  /** Style for the outer wrapper (equivalent to `containerStyle`, kept as the plain
+   * `style` prop so style-interop tooling like NativeWind's `cssInterop` — the same
+   * mechanism shadcn-style RN kits (e.g. react-native-reusables) rely on — can target
+   * it by the standard prop name). */
+  style?: StyleProp<ViewStyle>;
+  containerStyle?: StyleProp<ViewStyle>;
+  inputStyle?: StyleProp<TextStyle>;
+  dialCodeStyle?: StyleProp<TextStyle>;
+  flagStyle?: StyleProp<TextStyle>;
+  countryPickerButtonStyle?: StyleProp<ViewStyle>;
+  /** Per-element style overrides for the country picker modal (see {@link CountryPickerStyles}) */
+  pickerStyles?: CountryPickerStyles;
+
+  /** Visual theme tokens, merged under the style props above */
+  theme?: PhoneInputTheme;
+  /**
+   * Which palette to draw with. Defaults to "system", which follows the OS
+   * appearance — dark mode needs no setup.
+   */
+  colorScheme?: PhoneInputColorScheme;
+  /**
+   * Override individual palette tokens (separators, surfaces, muted text, the
+   * A-Z index, ...) on top of the resolved light/dark palette. This is the
+   * one knob for recoloring the whole component, picker included.
+   */
+  palette?: Partial<PhoneInputPalette>;
+
+  /**
+   * Safe-area padding for the picker sheet. Usually unnecessary — when
+   * `react-native-safe-area-context` is installed (an optional peer) the
+   * insets are detected automatically, and the defaults work without it
+   * either way. Any edge set here overrides the detected value for that edge
+   * only, so `{ top: 0 }` opts out of the top inset and keeps the rest.
+   */
+  pickerSafeAreaInsets?: {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+  };
+  /** Modal presentation style for the built-in picker (default: "pageSheet" on iOS, "fullScreen" elsewhere) */
+  pickerPresentationStyle?: 'pageSheet' | 'fullScreen' | 'formSheet';
+}

package/src/value.ts

@@ -0,0 +1,70 @@
+import {
+  AsYouType,
+  getCountryCallingCode,
+  isValidPhoneNumber,
+  parsePhoneNumberFromString,
+} from 'libphonenumber-js';
+import { getCountryByCallingCode, getCountryByCode } from './countries';
+import type { Country } from './countries';
+import type { PhoneInputValue } from './types';
+
+/**
+ * The country's true calling code ("1" for Jamaica), as opposed to the
+ * extended `dialCode` ("1876") the picker shows to tell the NANP territories
+ * apart. Concatenating the latter with a national number double-counts the
+ * area code, so every international string is built from this instead.
+ */
+export function callingCodeFor(country: Country): string {
+  try {
+    return getCountryCallingCode(country.code);
+  } catch {
+    return country.dialCode;
+  }
+}
+
+export function buildValue(
+  nationalNumber: string,
+  country: Country
+): PhoneInputValue {
+  const digits = nationalNumber.replace(/\D/g, '');
+  const valid = digits.length > 0 && isValidPhoneNumber(digits, country.code);
+  const e164 = valid
+    ? (parsePhoneNumberFromString(digits, country.code)?.number ?? null)
+    : null;
+  return {
+    nationalNumber: digits,
+    country: country.code,
+    dialCode: country.dialCode,
+    e164,
+    international: digits ? `+${callingCodeFor(country)}${digits}` : '',
+    isValid: valid,
+  };
+}
+
+/**
+ * Splits a controlled `value` into the national digits and, when the value is
+ * an international string, the country it implies. `current` is kept whenever
+ * its calling code still matches, so an explicit pick among the countries
+ * sharing a calling code (Jamaica vs the US on "+1") is not undone by the
+ * next keystroke.
+ */
+export function readControlledValue(
+  raw: string,
+  current: Country
+): { national: string; country: Country } {
+  if (!raw.startsWith('+')) {
+    return { national: raw.replace(/\D/g, ''), country: current };
+  }
+  const formatter = new AsYouType();
+  formatter.input(raw);
+  const callingCode = formatter.getCallingCode();
+  const national = formatter.getNationalNumber() ?? '';
+
+  if (!callingCode || callingCode === callingCodeFor(current)) {
+    return { national, country: current };
+  }
+  const next =
+    getCountryByCode(formatter.getCountry()) ??
+    getCountryByCallingCode(callingCode);
+  return { national, country: next ?? current };
+}