@masters-ws/react-country-phone-input-mask

A smart, highly customizable phone number input component for React and Next.js with automatic formatting, country selection, high-quality flags, and built-in validation.

Features

• 🌍 Global Support: Masks and validates phone numbers for all countries seamlessly using libphonenumber-js.
• ✅ Built-in Validation: Real-time validation for phone length and required fields.
• 🏳️ High-Quality Flags: Uses real images (FlagCDN) for flags to guarantee they render beautifully on all operating systems.
• 🇸🇾 Syrian Revolution Flag Support: Built-in exception for Syria (SY) to render the Syrian Revolution flag.
• ⚡ Next.js & SSR Ready: Completely compatible with Server-Side Rendering.
• 🎨 Fully Customizable: Add your own CSS classes (or Tailwind CSS) to style the input, dropdown, and container.
• 🌙 Dark Mode Support: Minimal default styles that automatically adapt to dark mode.

Installation

npm install @masters-ws/react-country-phone-input-mask
# or
yarn add @masters-ws/react-country-phone-input-mask

Basic Usage

import React, { useState } from 'react';
import { PhoneInput, PhoneMeta } from '@masters-ws/react-country-phone-input-mask';
import '@masters-ws/react-country-phone-input-mask/style.css';

export default function App() {
  const [phone, setPhone] = useState('');

  return (
    <div style={{ padding: '2rem' }}>
      <PhoneInput
        defaultCountry="SA"
        value={phone}
        onChange={(val) => setPhone(val)}
        validate={true} // Enable built-in validation
        errorMessage="Please enter a valid phone number"
      />
    </div>
  );
}

Validation & Error Handling

The component supports three ways to handle validation:

1. Automatic Validation: Pass validate={true} to show a red border and error message if the number is incomplete or empty (after the field is touched).
2. Custom Error Messages: Use errorMessage="Your custom message".
3. External Control: Use error={true} to force the error state from outside (perfect for react-hook-form or formik).

// Example with external error (e.g. from react-hook-form)
<PhoneInput
  error={!!errors.phone}
  errorMessage={errors.phone?.message}
  {...register('phone')}
/>

Props

| Prop | Type | Default | Description | |---|---|---|---| | value | string | '' | The controlled value of the input. | | onChange | (value: string, meta: PhoneMeta) => void | undefined | Callback fired when the value or country changes. | | defaultCountry | CountryCode | 'SA' | Default selected country code (ISO 2-letter). | | preferredCountries | CountryCode[] | [] | Array of country codes to pin to the top. | | validate | boolean | false | Enable real-time digit count validation. | | errorMessage | string | 'رقم الهاتف غير صحيح' | Custom message to show on error. | | error | boolean | false | Force the error state manually. | | containerClassName | string | '' | CSS class for the root container. | | inputClassName | string | '' | CSS class for the input element. | | buttonClassName | string | '' | CSS class for the country button. | | dropdownClassName | string | '' | CSS class for the dropdown. |

The PhoneMeta Object

interface PhoneMeta {
  countryCode?: CountryCode; // e.g. "SA"
  isValid: boolean;          // true if format matches country rules
  nationalNumber?: string;   // number without dial code
  formattedNumber?: string;  // fully formatted international string
}

License

MIT