country_mobile_validator #

🌟 Why country_mobile_validator? #

Most phone number validators either assume a naive "10 digits everywhere" rule or pull in heavy, unmaintained regex wrappers. country_mobile_validator provides lightweight, accurate, and type-aware validation:

• 📱 Mobile-Only Detection — Landlines, toll-free, premium rate, and short codes are flagged accurately and never mistakenly treated as deliverable mobile numbers.
• 🎯 Range-Aware — Every country exposes its true national mobile length range (8–10, 10–11…), preventing valid international users from getting blocked.
• ⚡ Ultra-Fast & Pure Dart — ~8 µs per validation, 0 platform channels, 1 standard dependency (crypto). Works everywhere: Flutter (Android, iOS, Web, macOS, Windows, Linux) and standalone Dart / Server.
• 🔒 OTP-Safe Verdicts — Returns isOtpDeliverable and specific failure reasons (tooShort, invalidPrefix, etc.) before you trigger costly SMS gateways.
• 🔄 Refreshable Metadata — Built-in SHA-256 verified runtime updater for bundled libphonenumber metadata without needing a package update.
• 🧩 First-Class country_code_picker Companion — Validate as users type or submit with one function call.

📦 Installation #

Add country_mobile_validator to your pubspec.yaml:

# For Flutter:
flutter pub add country_mobile_validator

# For pure Dart:
dart pub add country_mobile_validator

Or manually in pubspec.yaml:

dependencies:
  country_mobile_validator: ^0.2.1

🚀 Quick Start #

1. One-Shot Auto-Detection (E.164 / International) #

Automatically parses the international dialing code and validates against that country's mobile rules:

import 'package:country_mobile_validator/country_mobile_validator.dart';

void main() {
  // India mobile (+91)
  final r1 = validateMobile('+91 98765 43210');
  print(r1.isValid);           // true
  print(r1.isMobile);          // true
  print(r1.isOtpDeliverable);   // true
  print(r1.regionCode);        // IN

  // US Toll-Free (+1 800)
  final r2 = validateMobile('+1 800 555 0134');
  print(r2.isValid);           // true
  print(r2.isMobile);          // false (NumberType.tollFree)
  print(r2.isOtpDeliverable);   // false -> Do not attempt SMS OTP!
}

2. Country-Pinned Validation (National Format) #

Validate national numbers for a specific ISO-3166-1 alpha-2 region code:

final validator = CountryMobileValidator();

// Argentina (AR) allows 10–11 digits
final arRegion = validator.forRegion('AR');
print(arRegion.lengthHint);                       // "10–11 digits"
print(arRegion.validate('91123456789').isValid);  // true (11 digits)
print(arRegion.validate('91123456').isValid);     // false (too short)

📱 country_code_picker Integration #

Easily integrate with Flutter's country_code_picker or any country dropdown:

import 'package:flutter/material.dart';
import 'package:country_code_picker/country_code_picker.dart';
import 'package:country_mobile_validator/country_mobile_validator.dart';

class PhoneInputWidget extends StatefulWidget {
  const PhoneInputWidget({super.key});

  @override
  State<PhoneInputWidget> createState() => _PhoneInputWidgetState();
}

class _PhoneInputWidgetState extends State<PhoneInputWidget> {
  final _validator = CountryMobileValidator();
  String _selectedCountryCode = 'US';
  String? _errorMessage;

  void _onValidate(String rawNumber) {
    final result = _validator.validateForCountry(
      _selectedCountryCode,
      rawNumber,
    );

    setState(() {
      if (result.isValid && result.isMobile) {
        _errorMessage = null; // Valid mobile number!
      } else {
        final hint = _validator.forRegion(_selectedCountryCode).lengthHint;
        _errorMessage = 'Please enter a valid mobile number ($hint)';
      }
    });
  }

  @override
  Widget build(BuildContext context) {
    return Column(
      crossAxisAlignment: CrossAxisAlignment.start,
      children: [
        Row(
          children: [
            CountryCodePicker(
              initialSelection: _selectedCountryCode,
              onChanged: (country) {
                setState(() {
                  _selectedCountryCode = country.code ?? 'US';
                });
              },
            ),
            Expanded(
              child: TextField(
                keyboardType: TextInputType.phone,
                decoration: InputDecoration(
                  labelText: 'Mobile Number',
                  errorText: _errorMessage,
                ),
                onChanged: _onValidate,
              ),
            ),
          ],
        ),
      ],
    );
  }
}

🌍 Real-World Range Awareness #

Different countries have different mobile length standards. Hardcoding 10 digits breaks for billions of real users:

With country_mobile_validator, query any region dynamically:

final nz = validator.forRegion('NZ');
nz.mobileLengthRange; // (8, 10)
nz.isMobileLength(8); // true
nz.isMobileLength(7); // false

🔍 ValidationResult API #

Each validation call returns a rich ValidationResult object:

🔄 Refreshable Metadata Pipeline #

When country numbering plans change, update metadata in runtime without releasing a new app build:

final updater = MetadataUpdater(
  manifestUrl: 'https://your-cdn.com/phone-metadata/manifest.json',
);

final result = await updater.checkAndUpdate(
  currentVersion: validator.metadataVersion,
);

if (result.success && result.newVersion != null) {
  validator.loadRefreshedMetadata(
    updater.lastVerifiedJson!,
    version: result.newVersion!,
  );
}

• Cryptographic Security: Downloads are verified against SHA-256 checksums.
• Resilient Fallback: If the network is unavailable or verification fails, the bundled snapshot continues working seamlessly.

🛠️ Testing & Development #

Run the test suite covering 247 mobile regions:

dart pub get
dart test
dart analyze

🌐 Ecosystem & Related Packages #

Explore complementary production-grade libraries built for high-performance Flutter & Dart development:

💖 Support the Project #

If you find this project useful, consider supporting its active maintenance and future development:

📄 License #

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

Maintained with ❤️ by Govind Tank.