https://github.com/isabo/phone-number-input-field
HTML input field WebComponent that formats and validates phone numbers.
https://github.com/isabo/phone-number-input-field
format hyperapp international libphonenumber number phone validate webcomponent
Last synced: 12 months ago
JSON representation
HTML input field WebComponent that formats and validates phone numbers.
- Host: GitHub
- URL: https://github.com/isabo/phone-number-input-field
- Owner: isabo
- License: mit
- Created: 2020-08-31T20:04:38.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2022-07-04T04:55:01.000Z (about 4 years ago)
- Last Synced: 2025-03-25T22:03:58.811Z (over 1 year ago)
- Topics: format, hyperapp, international, libphonenumber, number, phone, validate, webcomponent
- Language: JavaScript
- Homepage:
- Size: 117 KB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Phone Number Input Field
The Phone Number Input Field is a form field with the following features:
- **Incremental Formatting**
Phone numbers are formatted gradually with each keystroke. The digits are
grouped and spaced in the standard way for the country of origin.
- **Phone Number Validation**
The entered number is validated with each keystroke to determine whether it is
a valid number for the country it belongs to. The standard
`inputElement.validity.valid` property will indicate whether the phone number
is valid.
- **Determination of Phone Number Type**
In many countries it is possible to distinguish between mobile and land lines,
among other types of numbers.
- **Acts Like a Regular \ Tag**
The Phone Number Input Field is an `` tag with enhanced functionality.
As a regular `` tag, you can style it and interact with it in the
normal way. It is therefore framework-agnostic, i.e. it can be used with any
framework.
- **Dynamic Status Attributes**
The HTML tag adds, removes or changes the value of various attributes in order
to indicate what is known so far about the number that is being entered. These
can be incorporated into CSS rules that indicate the style visually.
## Demonstration
[See here for a live demo](https://isabo.github.io/phone-number-input-field/)
## Installation
### Using a bundler such as Webpack, Parcel etc.
1. Install the library into your Node project:
```
npm install phone-number-input-field
```
2. If it is not already installed, install the libphonenumber-js peer
dependency.
```
npm install libphonenumber-js
```
3. In your HTML, refer to the libphonenumber-js and phone-number-input
javascript files:
```html
```
### Using a CDN
In your HTML, refer to the libphonenumber-js javascript file and the
phone-number-input package.
```html
```
If you want to use the source map to debug, use this instead of the second line:
```html
```
## Usage
### HTML
Use phone-number-input in the same way as a regular `input` tag, but you must
specify the `is="phone-number-input"` attribute.
```html
```
### Javascript
Create an instance, then add it to the DOM in the normal way:
```javascript
// Option 1: Use createElement
const input1 = document.createElement('input', { is: 'phone-number-input' });
document.body.appendChild(input1);
// Option 2: Use the constructor
const PhoneNumberInput = customElements.get('phone-number-input');
const input2 = new PhoneNumberInput();
document.body.appendChild(input2);
```
### Properties / Attributes
| Property | Attribute | Description |
| --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| defaultCountry | default-country | Sets/gets the default country. This is needed when the entered number does not start with a country code prefix, e.g. +44. If you have a \ tag with a list of countries, it should set this property when a country is selected. |
| errorMsg | error-msg | Sets/gets the standard HTML form validation error message that the browser will display when validating a form containing this component. Default: "Invalid phone number!" |
| country | country | Gets the country of the current number. This allows the user to override the default country by using a country code prefix. |
| phoneIsValid | phone-is-valid | Indicates whether the current number is considered a valid number for the country. |
| phoneIsPossible | phone-is-possible | Indicates whether the length of the phone number is reasonable for the country. |
| phoneType | phone-type | The type of the phone number: MOBILE, FIXED_LINE, FIXED_LINE_OR_MOBILE, PREMIUM_RATE, TOLL_FREE, SHARED_COST, VOIP, PERSONAL_NUMBER, PAGER, UAN, VOICEMAIL |
| phoneE164 | phone-e164 | The phone number in E164 format, e.g. +12125551234 |
| onparse | onparse | Sets an inline handler for the `phone-parse` event. See below. |
| oncountrychange | oncountrychange | Sets an inline handler for the `phone-country-change` event. See below. |
### Events
The following are in addition to the events dispatched by the standard \
element.
| Event | Description |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| phone-parse | Dispatched whenever the value of the field is parsed. Parsing is triggered by the standard `input` events, but is debounced. Therefore, it may be preferable to listen to this instead of `input` events. |
| phone-country-change | Dispatched whenever the country that is identified from the entered number changes. In many cases this is well before the number is considered valid and/or its type is known. |
### Tips
- Use the standard input field's `autocomplete` attribute with an appropriate
value, e.g. `autocomplete="tel-national"` to cause the browser to suggest
the user's phone number if it has been used elsewhere.
# Developing & Building
- This project uses the [Hyperapp](https://github.com/jorgebucaran/hyperapp)
microframework, and my Hyperapp
[CustomElement library](https://github.com/isabo/hyperapp-custom-element).
- `npm run build` runs the build script.
- `npm run demo` runs a local web server that will build the component and serve
the demo page at http://localhost:3001/docs/