phone_number 1.0.0 icon indicating copy to clipboard operation
phone_number: ^1.0.0 copied to clipboard

Flutter plugin for parsing, formatting and validating international phone numbers.

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 Discord

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.


Usage #

Setup #

No especific setup required: only install the dependency and use :)

Basic use #

String springFieldUSASimple = '+14175555470';

// Parsing
PhoneNumber phoneNumber = await PhoneNumberUtil().parse(springFieldUSASimple);

// Validate
bool isValid = await plugin.validate(springFieldUSASimple);

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

See 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:

  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


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":"Γ…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 join to our Discord server

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 #

Contributors #

Made with

pub points


verified publisher

Flutter plugin for parsing, formatting and validating international phone numbers.



API reference


Icon for licenses.BSD-3-Clause (LICENSE)


flutter, meta


Packages that depend on phone_number