Phone Number Formatter #

A lightweight, zero-native-dependency Flutter and pure Dart package for formatting, parsing, and validating international phone numbers. Features built-in dialing metadata for over 240+ countries and territories, real-time TextInputFormatter for Flutter text fields, and strict country-specific condition validations—such as the Bangladesh 11-digit national rule (01XXXXXXXXX).

🌟 Key Features #

• 🇧🇩 Bangladesh Phone Number Rules:
  • Validates exact 11-digit national mobile format (01XXXXXXXXX) and 10-digit international format after +880 (1XXXXXXXXX).
  • Automatically strips leading trunk 0 in real time when dial code +880 is selected.
  • Generates standardized E.164 (+8801XXXXXXXXX) and international formatting (+880 1XXX-XXXXXX).
  • Future-Proof: Accepts newly allocated operator prefixes by default (strictPrefix: false), with optional strict mode.
• 🌐 Global Country Coverage (240+ Countries):
  • Complete phone metadata for all global countries (ISO-2 code, dial codes, flag emojis, min/max lengths, format masks).
  • Conditions for US/Canada (10-digit NANP rules), India (10 digits), UK, Germany, Saudi Arabia, UAE, and more.
• ⚡ Real-Time TextInputFormatter:
  • Smooth dynamic formatting as the user types without jumping or losing cursor positions.
  • Automatically clamps extra digits beyond a country's maximum allowed length without needing manual maxLength on TextField.
• 📱 Interactive PhoneInputField Widget:
  • Ready-to-use input field with searchable modal country picker and flag emojis.
  • Live validation indicators (customizable valid checkmark / invalid warning badge colors and icons).
• 🧩 Pure Dart & Flutter:
  • Zero C/C++ or heavy native binaries. Fully compatible with iOS, Android, Web, macOS, Windows, and Linux.

🚀 Getting Started #

Add phone_number_formatter to your pubspec.yaml:

dependencies:
  phone_number_formatter: ^1.0.0

Then import it in your Dart code:

import 'package:phone_number_formatter/phone_number_formatter.dart';

📖 Usage Examples #

1. Ready-to-use PhoneInputField Widget #

import 'package:flutter/material.dart';
import 'package:phone_number_formatter/phone_number_formatter.dart';

class MyPhonePage extends StatefulWidget {
  @override
  State<MyPhonePage> createState() => _MyPhonePageState();
}

class _MyPhonePageState extends State<MyPhonePage> {
  final TextEditingController _controller = TextEditingController();
  PhoneNumberResult? _result;

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Phone Input')),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          children: [
            PhoneInputField(
              controller: _controller,
              initialCountry: CountriesData.bangladesh,
              showValidationBadge: true,
              validBadgeColor: Colors.green,
              invalidBadgeColor: Colors.orange,
              onPhoneChanged: (result) {
                setState(() {
                  _result = result;
                });
              },
            ),
            const SizedBox(height: 16),
            if (_result != null) ...[
              Text('Valid: ${_result!.isValid}'),
              Text('National: ${_result!.national}'),
              Text('E.164: ${_result!.e164}'),
              Text('International: ${_result!.international}'),
            ],
          ],
        ),
      ),
    );
  }
}

2. PhoneInputField Properties Reference #

3. Standalone TextInputFormatter for Any TextField #

You can attach PhoneNumberInputFormatter directly to any standard Flutter TextField or TextFormField:

TextField(
  keyboardType: TextInputType.phone,
  inputFormatters: [
    PhoneNumberInputFormatter(
      country: CountriesData.bangladesh, // Target country formatting
      enforceMaxLength: true,             // Clamps to max digits for country
      isWithDialCode: false,              // Strips leading 0 if dial code is prefixed
    ),
  ],
  decoration: const InputDecoration(
    hintText: '01712-345678',
    border: OutlineInputBorder(),
  ),
)

4. Parsing & Formatting Strings #

// Parse a Bangladesh local number:
final res = PhoneNumberParser.parse('01712345678');

print(res.isValid);               // true
print(res.national);              // "01712-345678"
print(res.international);         // "+880 1712-345678"
print(res.e164);                  // "+8801712345678"
print(res.country?.name);         // "Bangladesh"

// Parse an international number:
final usRes = PhoneNumberParser.parse('+12015550123');
print(usRes.national);            // "(201) 555-0123"
print(usRes.country?.isoCode);    // "US"

5. Validating Numbers #

// Bangladesh 11-digit validation
final valid = PhoneNumberValidator.validate('01712345678', country: CountriesData.bangladesh);
print(valid.isValid); // true

// Bangladesh under 11 digits:
final short = PhoneNumberValidator.validate('017123456', country: CountriesData.bangladesh);
print(short.isValid);      // false
print(short.errorMessage); // "Bangladesh phone number must be exactly 11 digits (current: 9)"

// Bangladesh flexible validation (accepts all 11-digit operator series):
final validNumber = PhoneNumberValidator.validate('01234534564', country: CountriesData.bangladesh);
print(validNumber.isValid); // true

// Optional strict operator code checking:
final badPrefix = PhoneNumberValidator.validate('01212345678', country: CountriesData.bangladesh, strictPrefix: true);
print(badPrefix.isValid);      // false
print(badPrefix.errorMessage); // "Invalid operator code. Valid prefixes are 013, 014, 015, 016, 017, 018, 019"

6. Accessing the Global Country Registry #

// Look up by ISO-2 code
final country = CountriesData.findByIso('BD');

// Look up by dial code
final country = CountriesData.findByDialCode('+880');

// List of all 240+ countries
final List<CountryPhoneInfo> allCountries = CountriesData.all;

🇧🇩 Bangladesh Numbering Plan Reference #

🧪 Testing #

Run automated tests:

flutter test

Run linter:

flutter analyze

📄 License #

This project is licensed under the MIT License - see the LICENSE file for details.