MazPhoneNumberInput
MazPhoneNumberInput is a standalone input component that helps the user enter a phone number and validate it according to the country
INFO
Before you have to import the global css files in your project, follow instructions in Getting Started
TIP
This component use MazInput, so it inherits all his props
WARNING
For some countries with multiple valid number lengths like Anguilla (AI), you may need to disable the auto formatting (as you type) with auto-format="false"
prop
Prerequisites
To use this component, you have to install the libphonenumber-js
dependency
npm install libphonenumber-js
Show feature list and info
- Auto-detect country calling code with phone number provided
- You can set your preferred-countries, ignored-countries or exclude some countries with only-countries - Ex
['FR', 'BE', 'DE']
- Validation UI state: input becomes green when the phone number is valid and becomes red when the phone number is incorrect (can be disabled by
no-validation-success
andno-validation-error
prop) - Multi options for getting country code: By default, the component gets the country code via the browser (disable it with no-use-browser-locale) or you can use - fetch-country to get the country code via https://ipwho.is (network needed) - you can use
default-country-code
option instead to set one - Phone number is formatted while typing (can be disabled by the prop
noFormattingAsYouType
) - You can
search
your country in the list - Keyboard accessibility (Arrow down, Arrow up: Country list navigation - Escape: Close country list)
- Phone number example for each country in placeholder/label (can be disabled with
no-example
prop) - Auto-focus phone number input after selecting a country
- You can disable the flags:
no-flags
prop - Translations: Component translations & countries translations
Usage
v-model="undefined"
Result object is emitted by @update
or @data
events - Model
Translations
Labels & placeholders
<MazPhoneNumberInput
:translations="{
countrySelector: {
placeholder: 'Country code',
error: 'Choose country',
searchPlaceholder: 'Search a country',
},
phoneInput: {
placeholder: 'Phone number',
example: 'Example:',
},
}"
/>
Country list
Two ways to translate the country list:
First solution - set country locale
<MazPhoneNumberInput
country-locale="fr-FR"
/>
Second solution - custom list
<MazPhoneNumberInput
:custom-countries-list="{
FR: 'France',
BE: 'Belgique',
DE: 'Allemagne',
US: 'Etats-Unis',
}"
/>
Auto formatting
Becareful, the auto formatting is enabled by default and can have some issues with some countries with multiple valid number lengths like Anguilla (AI), you can disable it with the auto-format
prop
<MazPhoneNumberInput v-model="phoneNumber" :auto-format="false" />
Orientation
@default "responsive"
By default, the orientation is responsive, it will be in column on mobile (up to 425px) and in row on desktop
You can force the orientation to be:
- in column with the
orientation="col"
prop - in row with the
orientation="row"
prop
Reduce the window size to see the responsive behavior
Show country name instead of calling code
You can display the country name instead of the calling code with the country-selector-display-name
prop
Flags replacement with slots
Replace the default flags with slots
Types
Results emitted by @update
or @data
event
export type Results = {
isValid: boolean
isPossible?: boolean
countryCode?: CountryCode
countryCallingCode?: CountryCallingCode
nationalNumber?: NationalNumber
type?: NumberType
formatInternational?: string
formatNational?: string
uri?: string
e164?: string
rfc3966?: string
possibleCountries?: CountryCode[]
phoneNumber?: string
}
Country Code
type CountryCode = 'AC' | 'AD' | 'AE' | 'AF' | 'AG' | 'AI' | 'AL' | 'AM' | 'AO' | 'AR' | 'AS' | 'AT' | 'AU' | 'AW' | 'AX' | 'AZ' | 'BA' | 'BB' | 'BD' | 'BE' | 'BF' | 'BG' | 'BH' | 'BI' | 'BJ' | 'BL' | 'BM' | 'BN' | 'BO' | 'BQ' | 'BR' | 'BS' | 'BT' | 'BW' | 'BY' | 'BZ' | 'CA' | 'CC' | 'CD' | 'CF' | 'CG' | 'CH' | 'CI' | 'CK' | 'CL' | 'CM' | 'CN' | 'CO' | 'CR' | 'CU' | 'CV' | 'CW' | 'CX' | 'CY' | 'CZ' | 'DE' | 'DJ' | 'DK' | 'DM' | 'DO' | 'DZ' | 'EC' | 'EE' | 'EG' | 'EH' | 'ER' | 'ES' | 'ET' | 'FI' | 'FJ' | 'FK' | 'FM' | 'FO' | 'FR' | 'GA' | 'GB' | 'GD' | 'GE' | 'GF' | 'GG' | 'GH' | 'GI' | 'GL' | 'GM' | 'GN' | 'GP' | 'GQ' | 'GR' | 'GT' | 'GU' | 'GW' | 'GY' | 'HK' | 'HN' | 'HR' | 'HT' | 'HU' | 'ID' | 'IE' | 'IL' | 'IM' | 'IN' | 'IO' | 'IQ' | 'IR' | 'IS' | 'IT' | 'JE' | 'JM' | 'JO' | 'JP' | 'KE' | 'KG' | 'KH' | 'KI' | 'KM' | 'KN' | 'KP' | 'KR' | 'KW' | 'KY' | 'KZ' | 'LA' | 'LB' | 'LC' | 'LI' | 'LK' | 'LR' | 'LS' | 'LT' | 'LU' | 'LV' | 'LY' | 'MA' | 'MC' | 'MD' | 'ME' | 'MF' | 'MG' | 'MH' | 'MK' | 'ML' | 'MM' | 'MN' | 'MO' | 'MP' | 'MQ' | 'MR' | 'MS' | 'MT' | 'MU' | 'MV' | 'MW' | 'MX' | 'MY' | 'MZ' | 'NA' | 'NC' | 'NE' | 'NF' | 'NG' | 'NI' | 'NL' | 'NO' | 'NP' | 'NR' | 'NU' | 'NZ' | 'OM' | 'PA' | 'PE' | 'PF' | 'PG' | 'PH' | 'PK' | 'PL' | 'PM' | 'PR' | 'PS' | 'PT' | 'PW' | 'PY' | 'QA' | 'RE' | 'RO' | 'RS' | 'RU' | 'RW' | 'SA' | 'SB' | 'SC' | 'SD' | 'SE' | 'SG' | 'SH' | 'SI' | 'SJ' | 'SK' | 'SL' | 'SM' | 'SN' | 'SO' | 'SR' | 'SS' | 'ST' | 'SV' | 'SX' | 'SY' | 'SZ' | 'TA' | 'TC' | 'TD' | 'TG' | 'TH' | 'TJ' | 'TK' | 'TL' | 'TM' | 'TN' | 'TO' | 'TR' | 'TT' | 'TV' | 'TW' | 'TZ' | 'UA' | 'UG' | 'US' | 'UY' | 'UZ' | 'VA' | 'VC' | 'VE' | 'VG' | 'VI' | 'VN' | 'VU' | 'WF' | 'WS' | 'XK' | 'YE' | 'YT' | 'ZA' | 'ZM' | 'ZW';
Props, Event & Slots
Props
Prop name | Description | Type | Values | Default |
---|---|---|---|---|
style | Style attribut of the component root element | TSIndexedAccessType | - | undefined |
class | Class attribut of the component root element | TSIndexedAccessType | - | undefined |
modelValue | @model Country calling code + telephone number in international format | union | - | undefined |
defaultPhoneNumber | @deprecated true | union | - | undefined |
countryCode | @model Country code selected - Ex: "FR" | union | - | undefined |
defaultCountryCode | @deprecated - use country-code or v-model:country-code | union | - | undefined |
id | Id of the component | string | - | undefined |
placeholder | Placeholder of the input | string | - | undefined |
label | label of the input | string | - | undefined |
preferredCountries | List of country codes to place first in the select list - Ex: ['FR', 'BE', 'GE'] | Array | - | undefined |
ignoredCountries | List of country codes to be removed from the select list - Ex: ['FR', 'BE', 'GE'] | Array | - | undefined |
onlyCountries | List of country codes to only have the countries selected in the select list - Ex: ['FR', 'BE', 'GE'] | Array | - | undefined |
translations | Locale strings of the component | Partial | - | undefined |
listPosition | Position where the list of countries will be opened | Position | - | 'bottom left' |
color | Component color applied - Ex: "secondary" | Color | - | 'primary' |
size | Component size applied - Ex: "sm" | Size | - | 'md' |
noFlags | Remove flags in country list | boolean | - | |
disabled | Disable input | boolean | - | |
noExample | No show the phone number example | boolean | - | false |
noSearch | Disable search input in country list | boolean | - | |
searchThreshold | Threshold of the search input in country list where 1 is a perfect match and 0 is a match with any character@default 0.75 | number | - | 0.75 |
noUseBrowserLocale | By default the component use the browser locale to set the default country code if not country code is provided | boolean | - | |
fetchCountry | The component will make a request (https://ipwho.is) to get the location of the user and use it to set the default country code | boolean | - | |
noCountrySelector | No show the country selector | boolean | - | |
showCodeOnList | Show country calling code in the country list | boolean | - | |
customCountriesList | Replace country names | Record | - | undefined |
autoFormat | Disabled auto-format when phone is valid@default true | boolean | - | true |
noFormattingAsYouType | Disabled auto-format as you type@default false@deprecated use autoFormat instead | boolean | - | false |
countryLocale | locale of country list - Ex: "fr-FR"@default {string} browser locale | string | - | undefined |
noValidationError | Disable validation error UI | boolean | - | |
noValidationSuccess | Disable validation success UI | boolean | - | |
success | Add success UI | boolean | - | |
error | Add error UI | boolean | - | |
countrySelectorDisplayName | Will replace the calling code by the country name in the country selector | boolean | - | |
countrySelectorWidth | Choose the width of the country selector | string | - | '9rem' |
block | The input will be displayed in full width | boolean | - | |
excludeSelectors | Exclude selectors to close country selector list - usefull when you using custom flag | Array | - | undefined |
orientation | Orientation of the inputs in the component@default "responsive"@values "row" | "col" | "responsive" | union | - | 'responsive' |
countrySelectAttributes | Meta attributes of the country input@default {Record<string, unknown>} { autocomplete: 'off', name: 'country' } | Record | - | () => ({ name: 'country', autocomplete: 'off', }) |
phoneInputAttributes | Meta attributes of the phone number input@default {Record<string, unknown>} { autocomplete: 'tel', name: 'phone', inputmode: 'tel' } | Record | - | () => ({ name: 'phone', autocomplete: 'tel', inputmode: 'tel', }) |
Events
Event name | Properties | Description |
---|---|---|
update:model-value | phoneNumber string - phoneNumber formatted | emitted when country or phone number changes |
country-code | countryCode CountryCode - Country code | emitted when selected country changes |
update:country-code | countryCode CountryCode - Country code | emitted when country changes |
update | results Results - metadata of current phone number | emitted when country or phone number changes |
data | results Results - metadata of current phone number | emitted when country or phone number changes |
Slots
Name | Description | Bindings |
---|---|---|
no-results | Replace the "no results" icon in the country selector list | |
selector-flag | Country selector flag | country-code String - current selected country code - Ex: "FR" |
country-list-flag | Country list flag | country-code String - country code of option - Ex: "FR" option { iso2: string; dialCode: string; name: string; } - country datais-selected Boolean - true if option is selected |