Countries & formats

Where formats come from

The country table is generated from the metadata of libphonenumber — the Google library Android uses to check numbers. For each country we take an example mobile number and its national format without the prefix: that's how the number is written in the country itself.

The 28 countries of tinyval-mask keep its formats — +7 (999) 999-99-99, not +7 999 999-99-99: switching from tinyval-mask to tinyval-phone changes nothing.

The Google library doesn't get into the bundle: the package contains only the ready table — the dial code, the pattern and a couple of regular expressions.

import { phoneTable } from 'tinyval-phone';

phoneTable.jp; // ['81', '99-9999-9999', '0']
phoneTable.bs; // ['1', '(999) 999-9999', '1', '242']
//               код, шаблон после кода, национальная приставка, признак страны

Numbers of different length

In some countries numbers vary in length: a German mobile number has 10 or 11 digits, an Austrian one — 8 to 13. The extra digits are optional in the pattern: +49 999 9999999[9]. The number is filled (complete) once the minimal length is typed — more digits can be added after that.

Countries sharing a code

Several countries can share one dial code: +1 is the USA, Canada and 23 more countries and territories (the Bahamas, Jamaica, Puerto Rico…), +7 is Russia and Kazakhstan, +44 is the UK, Jersey, Guernsey and the Isle of Man. The country is detected like this:

1. The longest matching code is taken: +1242… — code 1, +375… — code 375.
2. If a country has a "sign" and the number matches it — that's the country. The sign is the beginning of the number (+1 242 — the Bahamas) or the whole number (+1 416 555 0123 — Canada: by the area code, once the number is typed in full).
3. Otherwise — the main country of the code: +1 is the USA, +44 is the UK.

Until a Canadian number is typed in full, the USA is shown — the mask is the same, only the flag changes. Numbers of the Åland Islands, Vatican City, Svalbard, the Cocos Islands and a few more territories can't be told apart from numbers of Finland, Italy, Norway and Australia — the main country is detected for them, just like libphonenumber does.

detectCountry('+1 201 555 0123'); // 'us'
detectCountry('+1 242 359 1234'); // 'bs'
detectCountry('+1 416 555 0123'); // 'ca'
detectCountry('+7 701 123 4567'); // 'kz'
detectCountry('+44 7797 712345'); // 'je'

National prefix

Inside a country a prefix is often dialed before the number: 8 in Russia, 0 in the UK and Germany, 06 in Hungary. With defaultCountry it can be typed — it's dropped and the country code is added automatically:

mask('07400123456', phoneAuto({ defaultCountry: 'gb' })); // '+44 7400 123456'
mask('015123456789', phone('de'));                       // '+49 151 23456789'
mask('0612345678', phone('fr'));                         // '+33 6 12 34 56 78'

Your own countries and formats

You can change a country's format, add or remove a country: npx tinyval-phone countries copies the table into your project and setCountries loads it. Details — Your own countries & flags.

import { setCountries } from 'tinyval-phone';

setCountries({ de: ['49', '9999 9999999[9]', '0'], xk: null });

Updating the data

Countries' numbering plans change from time to time. In the package itself the table and the flags are rebuilt from fresh libphonenumber-js and country-flag-icons with npm run generate -w packages/tinyval-phone; tests check an example number of every country.