or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

customization.mdframework-integrations.mdindex.mdinput-components.mdinternationalization.mdphone-input-components.mdutility-functions.md
tile.json

tessl/npm-react-phone-number-input

Telephone number input React component with country selection, validation, and formatting capabilities

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-phone-number-input@3.4.x

To install, run

npx @tessl/cli install tessl/npm-react-phone-number-input@3.4.0

index.mddocs/

React Phone Number Input

React Phone Number Input is a comprehensive international telephone number input component library for React applications. It provides full-featured components with country selection dropdowns, input-only components, and specialized variants for different use cases, all powered by libphonenumber-js for accurate parsing, validation, and formatting of international phone numbers.

Package Information

  • Package Name: react-phone-number-input
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install react-phone-number-input --save

Core Imports

The library provides multiple entry points for different use cases:

// Full-featured component with country select (default)
import PhoneInput from "react-phone-number-input";
import "react-phone-number-input/style.css";

// Input-only component (no country select)  
import PhoneInput from "react-phone-number-input/input";

// Core versions (require metadata parameter)
import PhoneInput from "react-phone-number-input/core";
import PhoneInput from "react-phone-number-input/input-core";

// Size variants
import PhoneInput from "react-phone-number-input/min";
import PhoneInput from "react-phone-number-input/max";
import PhoneInput from "react-phone-number-input/mobile";

// React Hook Form integration
import PhoneInput from "react-phone-number-input/react-hook-form";

// React Native
import PhoneInput from "react-phone-number-input/react-native-input";

// Utility functions
import { 
  formatPhoneNumber, 
  formatPhoneNumberIntl,
  parsePhoneNumber,
  isValidPhoneNumber,
  getCountries,
  getCountryCallingCode 
} from "react-phone-number-input";

// Localization
import en from "react-phone-number-input/locale/en";
import de from "react-phone-number-input/locale/de";
// ... 25+ other locales available

// Country flags
import flags from "react-phone-number-input/flags";

CommonJS:

const PhoneInput = require("react-phone-number-input");
const { formatPhoneNumber, parsePhoneNumber } = require("react-phone-number-input");

Basic Usage

import React, { useState } from "react";
import PhoneInput from "react-phone-number-input";
import "react-phone-number-input/style.css";

function MyComponent() {
  // Value will be in E.164 format: "+12133734253"
  const [value, setValue] = useState();
  
  return (
    <PhoneInput
      placeholder="Enter phone number"
      value={value}
      onChange={setValue}
      defaultCountry="US"
    />
  );
}

Architecture

React Phone Number Input is built around several key architectural components:

  • Component Variants: Multiple specialized components for different use cases (with/without country select, mobile-optimized, framework integrations)
  • Entry Point System: Extensive package.json exports providing 15+ entry points for different bundle sizes and feature sets
  • Metadata System: Built-in libphonenumber-js integration with options for custom metadata in "core" variants
  • Internationalization: Complete i18n support with 25+ locale files covering country names and UI labels
  • Type System: Full TypeScript support with comprehensive type definitions for all variants and props
  • Customization Layer: Extensive customization options including custom input components, flag components, and styling

Capabilities

Phone Input Components

Full-featured React components with country selection dropdowns, automatic formatting, and validation. Perfect for user registration forms and contact information collection.

interface Props<InputComponentProps> {
  value?: string;
  onChange(value?: string): void;
  defaultCountry?: Country;
  countries?: Country[];
  labels?: Labels;
  placeholder?: string;
  disabled?: boolean;
  readOnly?: boolean;
  onCountryChange?(country?: Country): void;
  // ... extensive customization options
}

declare const PhoneInputWithCountrySelect: React.ComponentClass<Props<DefaultInputComponentProps>>;

Phone Input Components

Input-Only Components

Streamlined phone number input components without country selection dropdowns. Ideal for cases where country context is predetermined or handled separately.

interface Props<InputComponentProps> {
  value?: string;
  onChange(value?: string): void;
  country?: Country;
  international?: boolean;
  withCountryCallingCode?: boolean;
  defaultCountry?: Country;
  smartCaret?: boolean;
  // ... customization options
}

declare const PhoneInput: React.ForwardRefExoticComponent<Props<DefaultInputComponentProps>>;

Input-Only Components

Framework Integrations

Specialized components for popular React frameworks and libraries, providing seamless integration with existing form systems.

// React Hook Form integration
interface ReactHookFormProps<FormValues> {
  name: string;
  control?: Control<FormValues>;
  rules?: object;
  defaultValue?: string;
  shouldUnregister?: boolean;
  // ... base component props
}

declare const PhoneInputWithCountrySelect: <FormValues>(props: ReactHookFormProps<FormValues>) => JSX.Element;

Framework Integrations

Utility Functions

Comprehensive phone number parsing, formatting, and validation utilities powered by libphonenumber-js.

function formatPhoneNumber(value: string): string;
function formatPhoneNumberIntl(value: string): string;
function parsePhoneNumber(input: string): PhoneNumber | undefined;
function isValidPhoneNumber(input: string): boolean;
function isPossiblePhoneNumber(input: string): boolean;
function getCountries(): Country[];
function getCountryCallingCode(country: Country): string;
function isSupportedCountry(country: Country): boolean;

Utility Functions

Internationalization

Complete internationalization support with locale files for 25+ languages and customizable country/UI labels.

type Labels = Partial<Record<LabelKey, string>>;
type LabelKey = Country | 'ZZ' | 'ext' | 'country' | 'phone';

// Locale imports
declare const en: Labels;
declare const de: Labels;
declare const fr: Labels;
// ... 25+ additional locales

Internationalization

Customization and Styling

Extensive customization options including custom input components, country flag displays, and comprehensive CSS styling system.

interface CustomizationProps {
  inputComponent?: React.ElementType;
  countrySelectComponent?: React.ElementType;
  flagComponent?: (props: FlagProps) => JSX.Element;
  flags?: Flags;
  containerComponent?: React.ElementType;
  // ... styling and layout options
}

Customization and Styling

Types

// Core value types
type Country = CountryCode; // Two-letter country code (e.g., "US", "DE")
type Value = E164Number;    // E.164 formatted phone number (e.g., "+12133734253")

// Component prop types  
type DefaultInputComponentProps = {
  [anyProperty: string]: any;
};

// Metadata and localization
type Metadata = MetadataJson;
type Labels = Partial<Record<LabelKey, string>>;
type Flags = Partial<Record<Country, EmbeddedFlag>>;

// Flag component types
interface FlagProps {
  country: Country;
  countryName: string;
  flagUrl?: string;
  flags?: Flags;
}

interface EmbeddedFlagProps {
  title: string;
}

type EmbeddedFlag = (props: EmbeddedFlagProps) => JSX.Element;
type Flag = (props: FlagProps) => JSX.Element;

// PhoneNumber class (from libphonenumber-js)
declare class PhoneNumber {
  country?: Country;
  countryCallingCode: string;
  nationalNumber: string;
  number: string;
  // ... additional properties and methods
}