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

v-model="undefined"

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

<template>
  <MazPhoneNumberInput
    v-model="phoneNumber"
    v-model:country-code="countryCode"
    show-code-on-list
    :preferred-countries="['FR', 'BE', 'DE', 'US', 'GB']"
    :ignored-countries="['AC']"
    @update="results = $event"
  />
  <code>
    {{ results }}
  </code>
</template>

<script setup lang="ts">
  import MazPhoneNumberInput from 'maz-ui/components/MazPhoneNumberInput'
  import { ref } from 'vue'
  const phoneNumber = ref()
  const countryCode = ref('FR')
  const results = ref()
</script>

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

Country code

Phone number

Country code

Phone number

Country code

Phone number

<MazPhoneNumberInput orientation="responsive" />
<MazPhoneNumberInput orientation="row" />
<MazPhoneNumberInput orientation="col" />

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

<MazPhoneNumberInput
  country-selector-display-name
  :translations="{
    countrySelector: {
      placeholder: 'Country',
    },
  }"
/>

Flags replacement with slots

Replace the default flags with slots

Country code

Phone number

<MazPhoneNumberInput :exclude-selectors="['#input-flag-element']">
  <template #selector-flag="{ countryCode }">
    <span
      id="input-flag-element"
      style="font-size: 0.8rem; background-color: var(--maz-color-secondary); color: var(--maz-color-secondary-contrast); border-radius: 100px; padding: 2px;"
    >
      {{ countryCode }}
    </span>
  </template>
  <template #country-list-flag="{ countryCode }">
    <MazBadge size="0.8rem" style="margin-right: 10px; width: 26px;">
      {{ countryCode }}
    </MazBadge>
  </template>
</MazPhoneNumberInput>

TIP

You can use available country codes with libraries like country-flag-icons to replace unicode flags by SVG flags

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
}

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	string	-	undefined
defaultPhoneNumber	@deprecated true	string	-	undefined
countryCode	@model Country code selected - Ex: "FR"	CountryCode	-	undefined
defaultCountryCode	@deprecated - use country-code or v-model:country-code	CountryCode	-	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	-
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	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 data is-selected Boolean - true if option is selected