99
1010Advanced phone input component for [ Ant Design] ( https://github.com/ant-design/ant-design ) that provides support for all
1111countries and is compatible with [ ` antd ` ] ( https://github.com/ant-design/ant-design ) 4 and 5 versions. It has built-in
12- support for area codes and provides validation to ensure that the entered numbers are valid. This open-source project
13- is designed to simplify the process of collecting phone numbers from users.
12+ support for area codes and provides [ strict validation] ( #validation ) to ensure the entered numbers are valid. This
13+ open-source project is designed to simplify the process of collecting phone numbers from users.
1414
1515## Installation
1616
@@ -24,10 +24,9 @@ yarn add antd-phone-input
2424
2525## Usage
2626
27- The latest version does not require any additional actions for loading the styles as it uses
28- the [ ` cssinjs ` ] ( https://github.com/ant-design/cssinjs ) ecosystem.
29-
30- ### Antd 5.x
27+ The library is designed to work with the ` 4.x ` and ` 5.x ` series of versions in the same way. It can be used as a regular
28+ Ant [ Input] ( https://ant.design/components/input ) (see the sample below). More usage examples can be found in
29+ the [ examples] ( examples ) directory.
3130
3231``` javascript
3332import React from " react"
@@ -43,52 +42,30 @@ const Demo = () => {
4342}
4443```
4544
46- ![ latest] ( https://user-images.githubusercontent.com/44609997/227775101-72b03e76-52bc-421d-8e75-a03c9d0d6d08.png )
47-
48- ### Antd 4.x
49-
50- For ` 4.x ` versions, you should use the ` legacy ` endpoint.
51-
52- ``` javascript
53- import PhoneInput from " antd-phone-input/legacy"
54- ```
55-
56- For including the styles, you should import them in the main ` less ` file after importing either
57- the ` antd/dist/antd.less ` or ` antd/dist/antd.dark.less ` styles.
58-
59- ``` diff
60- @import "~antd/dist/antd";
61- + @import "~antd-phone-input/legacy/style";
62- ```
63-
64- ![ legacy] ( https://user-images.githubusercontent.com/44609997/227775155-9e22bc63-2148-4714-ba8a-9bb4e44c0128.png )
65-
6645## Value
6746
68- The value of the component is an object containing the parts of a phone number. This format of value gives a wide range
69- of opportunities for handling the data in your custom way. For example, you can easily merge the parts of the phone
70- number into a single string.
47+ The value of the component is an object containing the parts of the phone number. This format of value gives a wide
48+ range of opportunities for handling the data in your desired way.
7149
7250``` javascript
7351{
7452 countryCode: 1 ,
7553 areaCode: 702 ,
7654 phoneNumber: " 1234567"
7755 isoCode: " us"
78- valid : function valid ()
56+ valid : function valid (strict )
7957}
8058` ` `
8159
8260## Validation
8361
84- The ` valid` function of the value object returns the validity of the phone number depending on the selected country. So
85- this can be used in a ` validator` like this:
62+ The ` valid` function of the value object returns the current validity of the entered phone number based on the selected
63+ country. So this can be used in a ` ` like this:
8664
8765` ` `
8866const validator = (_ , {valid}) => {
89- if (valid ()) {
90- return Promise .resolve ();
91- }
67+ // if (valid(true)) return Promise.resolve(); // strict validation
68+ if (valid ()) return Promise .resolve (); // non-strict validation
9269 return Promise .reject (" Invalid phone number"
9370}
9471
@@ -99,33 +76,28 @@ return (
9976)
10077` ` `
10178
79+ By default, the ` valid` function validates the phone number based on the possible supported lengths of the selected
80+ country. But it also supports a strict validation that apart from the length also checks if the area code is valid for
81+ the selected country. To enable strict validation, pass ` true ` as the first argument of the ` ` function.
82+
10283## Props
10384
85+ Apart from the below-described phone-specific properties, all [Input](https://ant.design/components/input#input)
86+ properties that are supported by the used ` antd` version, can be applied to the phone input component.
87+
10488| Property | Description | Type |
10589|--------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------|
106- | size | Either ` large` , ` ` or ` ` . Default value is ` ` . See at ant [docs][antInputProps] for more. | string |
10790| value | An object containing a parsed phone number or the raw number. This also applies to the ` initialValue` property of [Form.Item](https://ant.design/components/form#formitem). | [object](#value) / string |
108- | style | Applies CSS styles to the container element. | CSSProperties |
109- | className | The value will be assigned to the container element. | string |
110- | disabled | Disables the whole input component. | boolean |
91+ | country | Country code to be selected by default. By default, it will show the flag of the user's country. | string |
11192| enableSearch | Enables search in the country selection dropdown menu. Default value is ` false ` . | boolean |
93+ | searchNotFound | The value is shown if ` enableSearch` is ` true ` and the query does not match any country. Default value is ` ` . | string |
94+ | searchPlaceholder | The value is shown if ` enableSearch` is ` true ` . Default value is ` ` . | string |
11295| disableDropdown | Disables the manual country selection through the dropdown menu. | boolean |
113- | inputProps | [HTML properties of input][htmlInputProps] to pass into the input. E.g. ` inputProps= {{autoFocus: true }}` . | InputHTMLAttributes |
114- | searchPlaceholder | The value is shown if ` enableSearch` is ` true ` . Default value is ` ` . | string |
115- | searchNotFound | The value is shown if ` enableSearch` is ` true ` and the query does not match any country. Default value is ` ` . | string |
116- | placeholder | Custom placeholder. Default placeholder is ` 1 (702 ) 123 - 4567 ` . | string |
117- | country | Country code to be selected by default. By default, it will show the flag of the user's country. | string |
118- | regions | Show only the countries of the specified regions. See the list of [available regions][reactPhoneRegions]. | string[] |
11996| onlyCountries | Country codes to be included in the list. E.g. ` onlyCountries= {[' us' ' ca' ' uk' ` . | string[] |
12097| excludeCountries | Country codes to be excluded from the list of countries. E.g. ` excludeCountries= {[' us' ' ca' ' uk' ` . | string[] |
12198| preferredCountries | Country codes to be at the top of the list. E.g. ` preferredCountries= {[' us' ' ca' ' uk' ` . | string[] |
122- | onChange | Callback when the user is inputting. See at ant [docs][antInputProps] for more. | function(value, e) |
123- | onPressEnter | The callback function that is triggered when <kbd>Enter</kbd> key is pressed. | function(e) |
124- | onFocus | The callback is triggered when the input element is focused. | function(e, value) |
125- | onClick | The callback is triggered when the user clicks on the input element. | function(e, value) |
126- | onBlur | The callback is triggered when the input element gets blurred or unfocused. | function(e, value) |
127- | onKeyDown | The callback is triggered when any key is pressed down. | function(e) |
128- | onMount | The callback is triggered once the component gets mounted. | function(e) |
99+ | onChange | The only difference from the original ` onChange` is that value comes first. | function(value, event) |
100+ | onMount | The callback is triggered once the component gets mounted. | function(value) |
129101
130102## Contribute
131103
@@ -135,9 +107,3 @@ don't forget to add tests for your changes.
135107## License
136108
137109Copyright (C) 2023 Artyom Vancyan. [MIT](LICENSE)
138-
139- [antInputProps]:https://ant.design/components/input#input
140-
141- [reactPhoneRegions]:https://github.com/bl00mber/react-phone-input-2#regions
142-
143- [htmlInputProps]:https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#attributes
0 commit comments