tessl/npm-react-phone-number-input

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

—

Pending

Overview

Eval results

Files

Input-Only Components

Name: tessl/npm-react-phone-number-input
Author: tessl

Streamlined phone number input components without country selection dropdowns. These components focus purely on phone number input with automatic formatting and validation, ideal when country context is predetermined or handled separately.

Capabilities

Main Input Component

Phone number input component without country selection dropdown.

/**
 * Phone number input component without country selection
 * Provides formatting and validation for a specific country or international format
 */
interface Props<InputComponentProps> {
  /** Phone number value in E.164 format (e.g., "+12133734253") */
  value?: string;
  /** Called when phone number changes, receives E.164 formatted value or undefined */
  onChange(value?: string): void;
  /** Specific country for national formatting (two-letter country code) */
  country?: Country;
  /** Force international format input */
  international?: boolean;
  /** Include country calling code in input field when international=true */
  withCountryCallingCode?: boolean;
  /** Default country for ambiguous numbers */
  defaultCountry?: Country;
  /** Use national format for default country initial value */
  useNationalFormatForDefaultCountryValue?: boolean;
  /** Custom input component */
  inputComponent?: React.ElementType;
  /** Enable smart caret positioning */
  smartCaret?: boolean;
  /** Standard input properties */
  placeholder?: string;
  disabled?: boolean;
  readOnly?: boolean;
  autoComplete?: string;
  className?: string;
  style?: object;
  onFocus?(event: React.FocusEvent<HTMLElement>): void;
  onBlur?(event: React.FocusEvent<HTMLElement>): void;
}

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

Usage Examples:

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

// National format for specific country
function NationalFormatExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      country="US"
      value={value}
      onChange={setValue}
      placeholder="Enter US phone number"
    />
  );
}

// International format
function InternationalFormatExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      international
      value={value}
      onChange={setValue}
      placeholder="Enter international phone number"
    />
  );
}

// With country calling code visible
function WithCallingCodeExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      country="US"
      international
      withCountryCallingCode
      value={value}
      onChange={setValue}
      placeholder="+1"
    />
  );
}

// With default country fallback
function DefaultCountryExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      defaultCountry="US"
      value={value}
      onChange={setValue}
      placeholder="Enter phone number"
    />
  );
}

Input Core Component

Core input component requiring manual metadata parameter.

/**
 * Core input component requiring manual metadata
 * Use for custom metadata or smaller bundle sizes
 */
interface InputCoreProps<InputComponentProps> extends Props<InputComponentProps> {
  /** libphonenumber-js metadata object (required) */
  metadata: Metadata;
}

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

Usage Example:

import PhoneInput from "react-phone-number-input/input-core";
import metadata from "libphonenumber-js/metadata.json";

function InputCoreExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      country="US"
      value={value}
      onChange={setValue}
      metadata={metadata}
    />
  );
}

Input Bundle Variants

Different bundle size variants with the same API.

// Minimal bundle size
import PhoneInput from "react-phone-number-input/input-min";

// Maximum features  
import PhoneInput from "react-phone-number-input/input-max";

// Mobile-optimized
import PhoneInput from "react-phone-number-input/input-mobile";

Format Behavior

Input components behave differently based on props configuration:

Country-Specific National Format

When country prop is provided without international:

Input accepts only national format for that country
Example: US numbers as "(213) 373-4253"
Output is still E.164 format: "+12133734253"

International Format

When international prop is true:

Input accepts international format
Country calling code handling depends on other props

Default Country Mode

When defaultCountry prop is provided:

Input accepts both national and international formats
National format numbers are parsed using the default country
International format numbers are parsed as-is

Input Component Integration

Input components support custom input component integration.

/**
 * Custom input component interface
 * Must use React.forwardRef() to forward ref to underlying input
 */
interface CustomInputProps {
  value: string;
  onChange(event: React.ChangeEvent<HTMLInputElement>): void;
  onKeyDown?(event: React.KeyboardEvent<HTMLInputElement>): void;
  onPaste?(event: React.ClipboardEvent<HTMLInputElement>): void;
  // Any other standard input props
}

type InputComponent<InputComponentProps> = 
  | ((props: InputComponentProps) => JSX.Element)
  | React.ComponentClass<InputComponentProps>
  | React.ForwardRefExoticComponent<InputComponentProps>;

Custom Input Example:

import React, { forwardRef } from "react";
import PhoneInput from "react-phone-number-input/input";

const CustomTextInput = forwardRef<HTMLInputElement, any>((props, ref) => (
  <input
    {...props}
    ref={ref}
    className="custom-input-style"
    style={{ border: '2px solid blue', borderRadius: '8px' }}
  />
));

function CustomInputExample() {
  const [value, setValue] = useState();
  return (
    <PhoneInput
      inputComponent={CustomTextInput}
      country="US"
      value={value}
      onChange={setValue}
    />
  );
}

Smart Caret Positioning

Input components support intelligent caret positioning during editing.

interface SmartCaretProps {
  /** Enable/disable smart caret positioning (default: true) */
  smartCaret?: boolean;
}

Smart caret behavior:

Moves caret to next digit position when inserting in middle of formatted number
Handles format changes that alter digit positions
Can be disabled if it causes issues with specific input components
Skips punctuation and spacing in formatted display

Value Handling

Input components handle various value formats consistently.

// Input value types
type InputValue = string | undefined;

// onChange signature  
onChange(value?: string): void;

Value handling rules:

undefined, null, or empty string are treated as "empty"
onChange always calls with undefined for empty values (not null or "")
Input accepts E.164 format or external string values
Output is always E.164 format or undefined
Invalid numbers result in undefined onChange calls

Value Handling Examples:

function ValueHandlingExample() {
  const [value, setValue] = useState<string | undefined>();
  
  const handleChange = (newValue: string | undefined) => {
    setValue(newValue);
    
    if (newValue === undefined) {
      console.log('Phone number cleared or invalid');
    } else {
      console.log('Valid phone number:', newValue); // E.164 format
    }
  };
  
  return (
    <PhoneInput
      country="US"
      value={value}
      onChange={handleChange}
      placeholder="(555) 123-4567"
    />
  );
}

Error States

Input components handle various error conditions:

Invalid input automatically formats or clears invalid characters
Incomplete numbers do not trigger onChange until valid
Overly long numbers are truncated based on country metadata
Numbers invalid for selected country result in undefined onChange calls

Install with Tessl CLI

npx tessl i tessl/npm-react-phone-number-input

docs

customization.md

framework-integrations.md

index.md

input-components.md

internationalization.md

phone-input-components.md

utility-functions.md

tile.json