International Telephone Input

A JavaScript plugin for entering and validating international telephone numbers.

Support the project

Sponsored by

Use Twilio's API to build phone verification, SMS 2FA, appointment reminders, marketing notifications and so much more. We can't wait to see what you build.

Description

International Telephone Input is a plugin, writen in pure JavaScript, for handling international telephone numbers. It makes it easy for your users to enter their phone number, and for you to validate it before saving it to your backend. Then, at a later time, you can display the number back to them in a format of your choice. All the while, giving you complete control with a variety of initialisation options, public methods for interaction, and custom events you can listen for and react to.

By default, it adds a country dropdown to your input, and sets the placeholder to an example number for the selected country. There is also an option to automatically select the user's current country based on an IP lookup during initialisation. Once the correct country is selected, the user is free to enter their number in whatever format they are used to, including the national format (e.g. no confusing international dial codes). The plugin then provides comprehensive validation tools, including returning error codes for invalid numbers, which you can then map to you own custom error messages. Finally, it returns the full standardized international number for you to save to your backend.

The country dropdown can be navigated by typing a country's name, or using the up/down arrow keys. You can control which countries appear in the list, as well as if any "preferred countries" should be displayed separately at the top. You can also provide localised country names if you wish. Full accessibility is provided via ARIA tags. Finally, the flag images can be completely disabled if needed, and you can replace the selected flag with a dial code instead.

Phone number validation and formatting are complex problems, when you think about supporting all the different types of numbers (mobile/landline/toll-free/premium etc) from hundreds of different countries, each with their own area codes etc. And these numbers are entered by users in different formats (national/international). And all of this is constantly changing as countries update what is allowed and add new rules. For this reason, this plugin uses a custom build of Google's libphonenumber library for all formatting, validation and generating placeholder numbers.