Phone Number

Phone Number is a Flutter plugin that allows you to parse, validate, format and other utilities for to international phone numbers.

Pub Version GitHub Workflow Status Codecov CodeFactor Grade

Features

  • Parsing phone number
  • Validate phone number
  • Format phone number
  • Get region from phone number
  • Get region from device

Dependencies

The plugin uses the native libraries libphonenumber for Android and PhoneNumberKit pod for iOS.

Library Version
libphonenumber 8.13.10
PhoneNumberKit 3.5.10

Usage

Setup

Add the following line to the top of the Runner target in your ios/Podfile

target 'Runner' do
  pod 'PhoneNumberKit/PhoneNumberKitCore', :git => 'https://github.com/marmelroy/PhoneNumberKit', :tag => '3.5.10'
  ...
end

Basic use

String springFieldUSASimple = '+14175555470';

// Parsing
PhoneNumber phoneNumber = await PhoneNumberUtil().parse(springFieldUSASimpleNoRegion, regionCode: region.code);

// Validate
bool isValid = await PhoneNumberUtil().validate(springFieldUSASimpleNoRegion, regionCode: region.code);

// Format
RegionInfo region = RegionInfo('US', 1);
String formatted = await PhoneNumberUtil().format(springFieldUSASimple, region.code); // +1 (417) 555-5470

See pud.dev example tab or github code for more details

Specific use

Phone number with dashes

Parse a phone number with region prefix and dashes.

// Parsing
String springFieldUSA = '+1-417-555-5470';
PhoneNumber phoneNumber = await PhoneNumberUtil().parse(springFieldUSA);

// Validate
bool isValid = await PhoneNumberUtil().validate(springFieldUSA);

// Format
String formatted = await PhoneNumberUtil().format(springFieldUSASimpleNoRegion, region.code); // +1 (417) 555-5470

Phone number without region (national number)

Parse a phone number string without the region prefix. Region required. Country calling codes can be found here

String springFieldUSASimpleNoRegion = '4175555470';
RegionInfo region = RegionInfo('US', 1);

// Parsing
PhoneNumber phoneNumber = await PhoneNumberUtil().parse(springFieldUSASimpleNoRegion, region: region);

// Validate
bool isValid = await PhoneNumberUtil().validate(springFieldUSASimpleNoRegion, region: region.code);

// Format
String formatted = await PhoneNumberUtil().format(springFieldUSASimpleNoRegion, region.code); // (417) 555-5470

Parsing model result

Parsing a valid phone number results in a phone number object:

PhoneNumber{
  e164: +14175555470,
  type: PhoneNumberType.FIXED_LINE_OR_MOBILE,
  international: +1 417-555-5470,
  national: (417) 555-5470,
  countryCode: 1,
  regionCode: "US",
  nationalNumber: 4175555470,
  errorCode: null,
}

As-you-type formatting

Attach the provided PhoneNumberEditingController to a TextField to format its text as the user type.

There are 3 formatting behavior:

  • PhoneInputBehavior.strict: always format, do not accept non dialable chars.
  • PhoneInputBehavior.cancellable: stop formatting when a separator is removed, do not accept non dialable chars.
  • PhoneInputBehavior.lenient (default): stop formatting when either a non dialable char is inserted or a separator is removed.

Example video: Phone number editing controller demo

Regions

Fetching regions (country code and prefixes).

List<RegionInfo> regions = await plugin.allSupportedRegions();
// [ RegionInfo { code: IM, prefix: 44 }, RegionInfo { code: LU, prefix: 352 }, ... ]

A parsed phone number will give region code as well.

String springFieldUSASimple = '+14175555470';
PhoneNumber phoneNumber = await PhoneNumberUtil().parse(springFieldUSASimple);
phoneNumber.regionCode; // US

If you want to display all the flags alongside the regions in your UI region picker, consider having a JSON file instead of using this function. Example JSON file

const List<Map<String, dynamic>> countries = [
  {"name":"Afghanistan","flag":"🇦🇫","code":"AF","dial_code":"+93"},
  {"name":"Åland Islands","flag":"🇦🇽","code":"AX","dial_code":"+358"},
  ...
]

Device Region code

It is possible to fetch the region code from the device. This will give you the two letter country code. (e.g. US, UK, etc.)

String code = await plugin.carrierRegionCode();

Support

Contribute

You have some ways to contribute to this packages

  • Beginner: Reporting bugs or request new features
  • Intermediate: Implement new features (from issues or not) and created pull requests
  • Advanced: Join the organization like a member and help coding, manage issues, dicuss new features and other things

See contribution guide for more details

Questions and answers

You can question or search answers on Github discussion

Donations

Donate or become a sponsor of Flutter Form Builder Ecosystem

Become a Sponsor

Roadmap

Ecosystem

Take a look to our awesome ecosystem and all packages in there

Thanks to

All contributors

Libraries

phone_number