International Telephone Input

🎉 NEWS: we now have our own React component! Play with it on Storybook! 🎉

A JavaScript plugin for entering and validating international telephone numbers. It adds a (searchable) country dropdown to any input, detects the user's country, displays a relevant placeholder number, formats the number as you type, and provides comprehensive validation methods.

Demo

Features

  • Automatically select the user's current country using an IP lookup
  • Automatically set the input placeholder to an example number for the selected country
  • Navigate the country dropdown by typing a country's name, or using up/down keys
  • Automatic formatting as the user types
  • Handle phone number extensions
  • The user types their national number and the plugin gives you the full standardized international number
  • Full validation, including specific error types
  • Retina flag icons
  • Lots of initialisation options for customisation, as well as public methods for interaction
  • Accessibility provided via ARIA tags based on W3's Select-Only Combobox Example

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.