React PhoneBox

A lightweight, customizable, and i18n-ready phone number input component with country selection, flag icons, validation, and formatting — powered by libphonenumber-js.

📘 Documentation

Official documentation is available at:
🔗 https://frkngnc.github.io/react-phonebox

Includes:

• Easy & Advanced usage examples
• Full API reference
• Customization & styling guides
• Supported locales & validation behavior

✨ Features

• 🌍 Locale-based country names (supports en, tr, fr, ar, es, ur, etc.)
• 📞 Auto-formats and validates numbers using libphonenumber-js
• 🇺🇳 Flag icons from flagcdn.com
• 🔍 Debounced country search with intelligent filtering
• ✅ Validity feedback via callback
• 🌗 Light & Dark theme support
• 💡 Built-in RTL support
• 🔧 Modular hook-based API for advanced use cases
• 🪶 Lightweight and tree-shakable

🚀 Installation

npm install react-phonebox
# or
yarn add react-phonebox

🔧 Basic Usage (Easy Mode)

import { useState } from "react";
import { PhoneBox } from "react-phonebox";
import "react-phonebox/style.css";

function App() {
  const [phone, setPhone] = useState("");
  const [rawPhone, setRawPhone] = useState("");
  const [isValid, setIsValid] = useState(false);

  return (
    <PhoneBox
      value={phone}
      onChange={setPhone}
      onRawChange={setRawPhone}
      onValidChange={setIsValid}
      locale="tr"
      initialCountry="TR"
      theme="dark"
      searchPlaceholder="Ülke ara..."
      mobileOnly
    />
  );
}

⚙️ Advanced Usage (Full Control)

import { useState } from "react";
import {
  PhoneBoxInput,
  useFormatter,
  useExampleNumber,
  useMobileOnly
} from "react-phonebox";
import "react-phonebox/style.css";

function PhoneInputWithHooks() {
  const [value, setValue] = useState("");
  const [country, setCountry] = useState<any>({
    iso2: "TR",
    dialCode: "+90",
    name: "Turkey"
  });

  const { format } = useFormatter(country?.iso2);
  const { placeholder, example, maxDigits } = useExampleNumber(country?.iso2);
  const { validate } = useMobileOnly();

  const digits = value.replace(/\D/g, "").slice(0, maxDigits ?? 15);
  const formatted = format(digits);
  const raw = (country?.dialCode ?? "") + digits;
  const validation = validate(raw, false);

  return (
      <PhoneBoxInput
        value={formatted}
        onChange={setValue}
        onCountryChange={setCountry}
        initialCountry="TR"
        locale="tr"
        placeholder={placeholder}
        theme="dark"
        searchPlaceholder="Ülke ara..."
      />
  );
}

🔌 Exposed Hooks

| Hook | Description | |----------------------|------------------------------------------------------------| | useFormatter() | Formats input value live using AsYouType | | useExampleNumber() | Returns example number, placeholder, and max digits | | useMobileOnly() | Validates mobile numbers only if mobileOnly: true |

🧪 <PhoneBox /> Props

| Prop | Type | Description | |--------------------|--------------------------------|--------------------------------------------------------------| | value | string | Formatted phone number string | | onChange | (val: string) => void | Input value change handler | | locale | string | Locale key (en, tr, fr, etc.) | | initialCountry | string | Initial country ISO2 code (TR, US, etc.) | | theme | "dark" | "light" | Theme mode | | searchPlaceholder| string | Country search input placeholder | | mobileOnly | boolean | If true, only mobile numbers are considered valid | | onRawChange | (raw: string) => void | Callback for raw (unformatted) phone number | | onValidChange | (valid: boolean) => void | Callback to track if phone number is valid |

🧱 Styling

You must import styles manually:

import "react-phonebox/style.css";

You can override any class via CSS or use CSS variables for customization.

🌐 Languages Supported

Static JSON translations for:

• English (en)
• Turkish (tr)
• Arabic (ar)
• Urdu (ur)
• French (fr)
• Spanish (es)

🛆 License

MIT

🔗 Live Demo

Check out the live demo: react-phonebox demo

Developed with by frkngnc