intl-tel-input 25.4.0 → 25.4.2

package/README.md

@@ -4,9 +4,11 @@
 
 <img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/react.webp" alt="React logo" width="16px" />  NEWS: we now have our own <a href="https://github.com/jackocnr/intl-tel-input/tree/master/react">React component</a>! Play with it on <a href="https://intl-tel-input.com/storybook/?path=/docs/intltelinput--vanilla">Storybook</a>. 
 
+<img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/angular.png" alt="Angular logo" width="16px" />  NEWS: we now have our own <a href="https://github.com/jackocnr/intl-tel-input/tree/master/angular">Angular component</a>!
+
 🗣️ NEWS: we now provide [translations](#translations) in over 30 languages! [See them in action](https://intl-tel-input.com/storybook/?path=/docs/intltelinput--i18n).
 
-International Telephone Input is a JavaScript plugin for entering and validating international telephone numbers. It takes a regular input field, adds a searchable country dropdown, auto-detects the user's country, displays a relevant placeholder number, formats the number as you type, and provides comprehensive validation methods. React and Vue components are also included.
+International Telephone Input is a JavaScript plugin for entering and validating international telephone numbers. It takes a regular input field, adds a searchable country dropdown, auto-detects the user's country, displays a relevant placeholder number, formats the number as you type, and provides comprehensive validation methods. React, Vue and Angular components are also included.
 
 <img src="https://raw.github.com/jackocnr/intl-tel-input/master/screenshots/vanilla2.png" alt="Screenshot" width="265px" height="273px" />
   
@@ -19,7 +21,7 @@ Use [Twilio's API to build phone verification, SMS 2FA, appointment reminders, m
 
 ## Table of Contents
 
-- [React and Vue Components](#react-and-vue-components)
+- [React, Vue and Angular Components](#react-vue-and-angular-components)
 - [Demo and Examples](#demo-and-examples)
 - [Mobile](#mobile)
 - [Features](#features)
@@ -38,8 +40,8 @@ Use [Twilio's API to build phone verification, SMS 2FA, appointment reminders, m
 - [Contributing](#contributing)
 - [Attributions](#attributions)
 
-## React and Vue Components
-We now provide both React and Vue components alongside the regular JavaScript plugin. This readme is for the JavaScript plugin. View the [React Component readme](https://github.com/jackocnr/intl-tel-input/blob/master/react/README.md) or the [Vue Component readme](https://github.com/jackocnr/intl-tel-input/blob/master/vue/README.md).
+## React, Vue and Angular Components
+We now provide React, Vue and Angular components alongside the regular JavaScript plugin. This readme is for the JavaScript plugin. View the [React Component readme](https://github.com/jackocnr/intl-tel-input/blob/master/react/README.md), the [Vue Component readme](https://github.com/jackocnr/intl-tel-input/blob/master/vue/README.md) or the [Angular Component readme](https://github.com/jackocnr/intl-tel-input/blob/master/angular/README.md).
 
 ## Demo and Examples
 You can view [a live demo](https://intl-tel-input.com) and see some examples of how to use the various options. Alternatively, try it for yourself by downloading the project and opening demo.html in a browser.
@@ -61,7 +63,7 @@ By default, on mobile devices we show a fullscreen popup instead of the inline d
 * Accessibility provided via ARIA tags
 * Typescript type definitions included
 * Easily customise styles by overriding CSS variables
-* React and Vue components also included
+* React, Vue and Angular components also included
 * Translations for country names (etc) provided in many different languages
 * Lots of initialisation options for customisation, as well as instance methods/events for interaction
 
@@ -75,16 +77,16 @@ _Note: We have now dropped support for all versions of Internet Explorer because
 ## Getting Started (Using a CDN)
 1. Add the CSS
   ```html
-  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.0/build/css/intlTelInput.css">
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.2/build/css/intlTelInput.css">
   ```
 
 2. Add the plugin script and initialise it on your input element
   ```html
-  <script src="https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.0/build/js/intlTelInput.min.js"></script>
+  <script src="https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.2/build/js/intlTelInput.min.js"></script>
   <script>
     const input = document.querySelector("#phone");
     window.intlTelInput(input, {
-      loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.0/build/js/utils.js"),
+      loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.2/build/js/utils.js"),
     });
   </script>
   ```
@@ -320,7 +322,7 @@ The `loadUtils` option takes a function which returns a Promise which resolves t
 ```js
 // (A) import utils module from a CDN
 intlTelInput(htmlInputElement, {
-  loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.0/build/js/utils.js"),
+  loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.2/build/js/utils.js"),
 });
 
 // (B) import utils module from your own hosted version of utils.js
@@ -572,7 +574,7 @@ Example:
 ## Translations
 We provide [translations](https://github.com/jackocnr/intl-tel-input/tree/master/build/js/i18n) for the 200+ country names, as well as other user interface text (e.g. the placeholder text for the country search input) in over 30 languages. See the `i18n` option for details on how to use them. [See them in action](https://intl-tel-input.com/storybook/?path=/docs/intltelinput--i18n).
 
-Supported languages: Arabic, Bengali, Bosnian, Bulgarian, Catalan, Chinese, Croatian, Czech, Danish, Dutch, Norwegian, English, Farsi, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Marathi, Polish, Portuguese, Romanian, Russian, Slovak, Spanish, Swedish, Telugu, Thai, Turkish, Ukrainian, Urdu, Vietnamese. 
+Supported languages: Arabic, Bengali, Bosnian, Bulgarian, Catalan, Chinese, Croatian, Czech, Danish, Dutch, English, Estonian, Finnish, French, German, Greek, Hindi, Hungarian, Indonesian, Italian, Japanese, Korean, Marathi, Norwegian, Persian, Polish, Portuguese, Romanian, Russian, Slovak, Spanish, Swedish, Telugu, Thai, Turkish, Ukrainian, Urdu, Uzbek, Vietnamese.
 
 If we don't currently support a language you need, it's easy to [contribute this](https://github.com/jackocnr/intl-tel-input/blob/master/.github/CONTRIBUTING.md#adding-a-new-translation) yourself - you only need to provide a handful of UI translation strings, as we automatically pull in the country names from the country-list project.
 
@@ -604,7 +606,7 @@ The `loadUtils` option takes a function which returns a Promise which resolves t
 ```js
 // (A) import utils module from a CDN
 intlTelInput(htmlInputElement, {
-  loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.0/build/js/utils.js"),
+  loadUtils: () => import("https://cdn.jsdelivr.net/npm/intl-tel-input@25.4.2/build/js/utils.js"),
 });
 
 // (B) import utils module from your own hosted version of utils.js

package/angular/README.md

@@ -0,0 +1,86 @@
+# IntlTelInput Angular Component
+An Angular component wrapper for the [intl-tel-input](https://github.com/jackocnr/intl-tel-input) JavaScript plugin. View the [source code](https://github.com/jackocnr/intl-tel-input/blob/master/angular/src/intl-tel-input/angular.component.ts).
+
+## Table of Contents
+- [Demo](#demo)
+- [Getting Started](#getting-started)
+- [Props](#props)
+- [Events](#events)
+- [Accessing Instance Methods](#accessing-instance-methods)
+- [Accessing Static Methods](#accessing-static-methods)
+
+## Demo
+Try it for yourself by downloading the project and opening /angular/demo/validation/index.html (etc) in a browser.
+
+## Getting Started
+```html
+import IntlTelInput from "intl-tel-input/angularWithUtils";
+import "intl-tel-input/styles";
+
+<intl-tel-input
+  #telInput
+  (numberChange)="handleNumberChange($event)"
+  (validityChange)="handleValidityChange($event)"
+  [initOptions]="{
+    initialCountry: 'us',
+  }"
+/>
+```
+
+See the [Validation demo](https://github.com/jackocnr/intl-tel-input/blob/master/angular/demo/validation/validation.component.ts) for a more fleshed-out example of how to handle validation.
+
+A note on the utils script (~260KB): if you're lazy loading the IntlTelInput chunk (and so less worried about filesize) then you can just import IntlTelInput from `"intl-tel-input/angularWithUtils"`, to include the utils script. Alternatively, if you use the main `"intl-tel-input/angular"` import, then you should couple this with the `loadUtils` initialisation option - you will need to host the [utils.js](https://github.com/jackocnr/intl-tel-input/blob/master/build/js/utils.js) file, and then set the `loadUtils` option to that URL, or alternatively just point it to a CDN hosted version e.g. `"https://cdn.jsdelivr.net/npm/intl-tel-input@25.2.1/build/js/utils.js"`.
+
+## Props
+Here's a list of all of the current props you can pass to the IntlTelInput Angular component.
+
+**disabled**    
+Type: `Boolean`, Default: `false`   
+Sets the disabled attribute of both the telephone input and selected country button. _Note: we recommend using this instead of `inputProps.disabled`._
+
+**initialValue**  
+Type: `String`
+The initial value to put in the input. This will get auto-formatted on init (according to `formatOnDisplay` initialisation option). IntlTelInput is an uncontrolled input, and so will ignore any changes to this value.
+
+**initOptions**  
+Type: `Object`  
+An object containing the [initialisation options](https://github.com/jackocnr/intl-tel-input?tab=readme-ov-file#initialisation-options) to pass to the plugin. You can use these exactly the same way as with the main JavaScript plugin.
+
+**inputProps**  
+Type: `Object`  
+The props to pass to the input element e.g. `class`, `placeholder`, `required` etc. _Note: we recommend using the separate `disabled` prop instead of `inputProps.disabled`._
+
+**usePreciseValidation**  
+Type: `Boolean`, Default: `false`  
+By default we use `isValidNumber` for validation, but if you'd rather use `isValidNumberPrecise` you can set this to `true`.
+
+## Events
+Here's a list of all of the current events you can listen to on the IntlTelInput angular component.
+
+**countryChange**  
+Type: `Function`  
+A handler to be called when the selected country changes. It will be passed the new country iso2 code e.g. "gb" for UK.
+
+**errorCodeChange**  
+Type: `Function`  
+A handler to be called when the number validation error changes. It will be passed the new error code (or `null`).
+
+**numberChange**  
+Type: `Function`  
+A handler to be called when the number changes. It will be passed the new number.
+
+**validityChange**  
+Type: `Function`  
+A handler to be called when the number validity changes e.g. to true/false. It will be passed the new isValid boolean.
+
+### Native Input Events
+
+Unlike the React and Vue version where events are passed through `inputProps`, in Angular you can directly bind to any native DOM event using the standard event binding syntax `(eventName)="handlerMethod()"`. This is more aligned with Angular's templating conventions and provides better type checking and autocompletion in your IDE.
+
+## Accessing Instance Methods
+
+You can access all of the plugin's [instance methods](https://github.com/jackocnr/intl-tel-input/blob/master/README.md#instance-methods) (`setNumber`, `setCountry`, `setPlaceholderNumberType` etc) by using a ViewChild reference into the IntlTelInput component (using the `#ref` prop), and then calling `this.telInput.getInstance()` e.g. `this.telInput.getInstance().setNumber(...);`. See the [Set Number demo](https://github.com/jackocnr/intl-tel-input/blob/master/angular/demo/set-number/set-number.component.tsx) for a full example. You can also access the input DOM element in a similar way: `this.telInput.getInput()`.
+
+## Accessing Static Methods
+
+You can access all of the plugin's [static methods](https://github.com/jackocnr/intl-tel-input/blob/master/README.md#static-methods) by importing `intlTelInput` from the same file as the angular component e.g. `import { intlTelInput } from "intl-tel-input/angular"` (note the lower case "i" in "intlTelInput"). You can then use this as you would with the main plugin e.g. `intlTelInput.getCountryData()` or `intlTelInput.utils.numberType` etc.