Skip to content

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

libphonenumber-js
bash
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 and no-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

Country code
Phone number


js
v-model="undefined"

Result object is emitted by @update or @data events - Model

js

Translations

Labels & placeholders

html
<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

html
<MazPhoneNumberInput
  country-locale="fr-FR"
/>

Second solution - custom list

html
<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

html
<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

Country code
Phone number
Country code
Phone number
Country code
Phone number

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

Country
Phone number

Flags replacement with slots

Replace the default flags with slots

Country code
Phone number

Types

Results emitted by @update or @data event

ts
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

ts
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 nameDescriptionTypeValuesDefault
styleStyle attribut of the component root elementTSIndexedAccessType-undefined
classClass attribut of the component root elementTSIndexedAccessType-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
idId of the componentstring-undefined
placeholderPlaceholder of the inputstring-undefined
labellabel of the inputstring-undefined
preferredCountriesList of country codes to place first in the select list - Ex: ['FR', 'BE', 'GE']Array-undefined
ignoredCountriesList of country codes to be removed from the select list - Ex: ['FR', 'BE', 'GE']Array-undefined
onlyCountriesList of country codes to only have the countries selected in the select list - Ex: ['FR', 'BE', 'GE']Array-undefined
translationsLocale strings of the componentPartial-undefined
listPositionPosition where the list of countries will be openedPosition-'bottom left'
colorComponent color applied - Ex: "secondary"Color-'primary'
sizeComponent size applied - Ex: "sm"Size-'md'
noFlagsRemove flags in country listboolean-
disabledDisable inputboolean-
noExampleNo show the phone number exampleboolean-false
noSearchDisable search input in country listboolean-
searchThresholdThreshold 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
noUseBrowserLocaleBy default the component use the browser locale to set the default country code if not country code is providedboolean-
fetchCountryThe component will make a request (https://ipwho.is) to get the location of the user and use it to set the default country codeboolean-
noCountrySelectorNo show the country selectorboolean-
showCodeOnListShow country calling code in the country listboolean-
customCountriesListReplace country namesRecord-undefined
autoFormatDisabled auto-format when phone is valid
@default true
boolean-true
noFormattingAsYouTypeDisabled auto-format as you type
@default false
@deprecated use autoFormat instead
boolean-false
countryLocalelocale of country list - Ex: "fr-FR"
@default {string} browser locale
string-undefined
noValidationErrorDisable validation error UIboolean-
noValidationSuccessDisable validation success UIboolean-
successAdd success UIboolean-
errorAdd error UIboolean-
countrySelectorDisplayNameWill replace the calling code by the country name in the country selectorboolean-
countrySelectorWidthChoose the width of the country selectorstring-'9rem'
blockThe input will be displayed in full widthboolean-
excludeSelectorsExclude selectors to close country selector list - usefull when you using custom flagArray-undefined
orientationOrientation of the inputs in the component
@default "responsive"
@values "row" | "col" | "responsive"
union-'responsive'
countrySelectAttributesMeta attributes of the country input
@default {Record&lt;string, unknown&gt;} { autocomplete: 'off', name: 'country' }
Record-() => ({
name: 'country',
autocomplete: 'off',
})
phoneInputAttributesMeta attributes of the phone number input
@default {Record&lt;string, unknown&gt;} { autocomplete: 'tel', name: 'phone', inputmode: 'tel' }
Record-() => ({
name: 'phone',
autocomplete: 'tel',
inputmode: 'tel',
})

Events

Event namePropertiesDescription
update:model-valuephoneNumber string - phoneNumber formattedemitted when country or phone number changes
country-codecountryCode CountryCode - Country codeemitted when selected country changes
update:country-codecountryCode CountryCode - Country codeemitted when country changes
updateresults Results - metadata of current phone numberemitted when country or phone number changes
dataresults Results - metadata of current phone numberemitted when country or phone number changes

Slots

NameDescriptionBindings
no-resultsReplace the "no results" icon in the country selector list
selector-flagCountry selector flagcountry-code String - current selected country code - Ex: "FR"
country-list-flagCountry list flagcountry-code String - country code of option - Ex: "FR"
option { iso2: string; dialCode: string; name: string; } - country data
is-selected Boolean - true if option is selected