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
• An interactive light and dark theme demo

Try the live demo at https://frkngnc.github.io/react-phonebox/demo.

---

✨ 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
• 🏳️ CDN, native emoji, no-flag, or fully custom flag rendering
• 🔍 Debounced country search with intelligent filtering
• ⚡ Virtualized country list for low DOM and image overhead
• ⌨️ Keyboard and screen-reader friendly country picker
• ✅ Validity feedback via callback
• 🌗 Light & Dark theme support
• 🎛️ Classic, minimal, soft, and pill design variants
• 💡 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"
        variant="soft"
        searchPlaceholder="Ülke ara..."
        flagMode="emoji"
        mobileOnly
      />

      <p>Formatted: {phone || "-"}</p>
      <p>Raw: {rawPhone || "-"}</p>
      <p>Valid: {phone ? (isValid ? "Yes" : "No") : "-"}</p>
    </>
  );
}

---

⚙️ Advanced Usage (Full Control)

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

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

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

  const formatted = format(value);
  const validation = validate(value, false, country?.iso2);

  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	Called with the formatted display value
locale	string	Locale key (en, tr, fr, etc.)
initialCountry	string	Initial country ISO2 code (TR, US, etc.)
theme	"dark" | "light"	Theme mode
variant	"classic" | "minimal" | "soft" | "pill"	Built-in visual treatment
searchPlaceholder	string	Country search input placeholder
mobileOnly	boolean	If true, only mobile numbers are considered valid
onRawChange	(raw: string) => void	Callback for the E.164 phone number
onValidChange	(valid: boolean) => void	Callback to track if phone number is valid
countrySelectorLabel	string	Accessible label for the country selector
noResultsText	string	Empty-state text for country search
flagMode	"cdn" | "emoji" | "none"	Built-in flag rendering strategy
renderFlag	(country, context) => ReactNode	Overrides built-in flag rendering
virtualizeThreshold	number	Number of results after which list virtualization starts

Native input attributes such as name, required, disabled, onBlur, autoComplete, and aria-* are forwarded to the telephone input.

Use flagMode="emoji" for a fully offline flag display, or flagMode="none" when flags are not needed. renderFlag can render a local SVG, icon component, or any other React node.

---

🧱 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)

Other locales use Intl.DisplayNames when the runtime supports them.

---

🛆 License

MIT

---

🔗 Live Demo

Check out the live demo: react-phonebox demo

Developed by frkngnc