MazInputPhoneNumber

MazInputPhoneNumber is a powerful and user-friendly component that helps users enter and validate phone numbers from any country with automatic formatting and validation

Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started

TIP

This component can be translated globally using the MazUi plugin.

✨ What makes this component special?

• Smart country detection - Automatically detects country from browser locale or IP
• Real-time validation - Visual feedback as you type
• Auto-formatting - Formats numbers according to country standards
• Search countries - Find countries quickly in the dropdown
• Customizable - Full control over appearance and behavior
• Accessible - Keyboard navigation and screen reader support
• International - Supports all countries and phone formats

Basic Usage

The simplest way to use MazInputPhoneNumber - just add it and it works!

Country code

Phone number

Phone Number: Not entered yet

Country: Not selected

Is Valid: ❌ No

<script setup lang="ts">
import type { MazInputPhoneNumberData } from 'maz-ui/components/MazInputPhoneNumber'
import MazInputPhoneNumber from 'maz-ui/components/MazInputPhoneNumber'
import { ref } from 'vue'

const phoneNumber = ref<string>()
const countryCode = ref<string>()
const results = ref<MazInputPhoneNumberData>()
</script>

<template>
  <MazInputPhoneNumber
    v-model="phoneNumber"
    v-model:country-code="countryCode"
    @data="results = $event"
  />
</template>

Country Management

Control which countries appear in the dropdown and their order.

Preferred Countries

Country code

Show your most common countries first

Only Specific Countries

Country code

Limit to certain countries only

Ignore Countries

Country code

Remove unwanted countries

<template>
  <!-- Preferred countries (moved to top, order not preserved) -->
  <MazInputPhoneNumber
    v-model="phoneNumber"
    :preferred-countries="['US', 'FR', 'GB', 'DE', 'CA']"
    placeholder="Common countries appear first"
  />

  <!-- Only specific countries -->
  <MazInputPhoneNumber
    v-model="phoneNumber"
    :only-countries="['US', 'FR', 'GB', 'DE', 'IT', 'ES']"
    placeholder="Only European + North American countries"
  />

  <!-- Ignore certain countries -->
  <MazInputPhoneNumber
    v-model="phoneNumber"
    :ignored-countries="['AF', 'AL', 'DZ']"
    placeholder="Some countries are hidden"
  />
</template>

Layout Orientations

Choose how the country selector and phone input are arranged.

Responsive

Country code

Phone number

Stacks on mobile, side-by-side on desktop

Always Row

Country code

Phone number

Side-by-side on all screen sizes

Always Column

Country code

Phone number

Stacked on all screen sizes

<template>
  <!-- Responsive layout (default) -->
  <MazInputPhoneNumber
    top-label="Responsive"
    assistive-text="Stacks on mobile, side-by-side on desktop"
    orientation="responsive"
  />

  <!-- Always side-by-side -->
  <MazInputPhoneNumber
    top-label="Always Row"
    assistive-text="Side-by-side on all screen sizes"
    orientation="row"
  />

  <!-- Always stacked -->
  <MazInputPhoneNumber
    top-label="Always Column"
    assistive-text="Stacked on all screen sizes"
    orientation="col"
  />
</template>

Display Options

Customize what information is shown to users.

Show Country Names

Choose country

Phone number

Display country names instead of calling codes

Show Calling Codes in List

Country code

Phone number

Help users see the dialing codes

Hide Phone Examples

Country code

Phone number

Remove the example phone number hints (visible when the phone input is focused)

Hide Country Flags

Country code

Phone number

Text-only country selection

Flags of maz-ui

Country code

Phone number

No request to flagcdn.com, works offline

<template>
  <!-- Show country names instead of codes -->
  <MazInputPhoneNumber
    display-country-name
    :translations="{ countrySelect: { placeholder: 'Choose country' } }"
  />

  <!-- Show calling codes in dropdown -->
  <MazInputPhoneNumber show-code-in-list />

  <!-- Hide phone number examples -->
  <MazInputPhoneNumber :example="false" />

  <!-- Hide country flags -->
  <MazInputPhoneNumber hide-flags />

  <!-- Flags of maz-ui, no request to flagcdn.com: import { loadCountryFlag } from 'maz-ui/country-flags' -->
  <MazInputPhoneNumber :flag-src="loadCountryFlag" />

  <!-- Your own files: public/flags/fr.svg... -->
  <MazInputPhoneNumber flag-src="/flags/{code}.svg" />
</template>

Flags source

By default, the flags come from the flagcdn.com CDN. The flag-src prop, passed to the country selector, takes:

• loadCountryFlag from maz-ui/country-flags: the flags of @maz-ui/icons, without any request to a third party, offline (hybrid apps with Capacitor or Cordova, PWAs);
• a URL template of your own files: '/flags/{code}.svg' ({CODE} for uppercase codes);
• your own function: (code) => string | undefined | Promise<string | undefined>.

Each flag is loaded only when visible, and a code without flag displays a badge. Set it once for the whole app with defaults.global.flagSrc of the MazUi plugin, or mazUi.flags of the Nuxt module ('local' or a URL template):

import { loadCountryFlag } from 'maz-ui/country-flags'

app.use(MazUi, { theme: { preset: mazUi }, defaults: { global: { flagSrc: loadCountryFlag } } })

See MazSelectCountry for the details (bundle, Content Security Policy, PWA precache).

Smart Country Detection

Let the component automatically detect the user's country.

Browser Locale Detection

Uses browser language settings (enabled by default)

Country code

Phone number

IP-based Detection

Fetches country from user's IP address

Country code

Phone number

Manual Default Country

Set a specific default country

Country code

Phone number

<template>
  <!-- Auto-detect from browser (default behavior) -->
  <MazInputPhoneNumber :use-browser-locale="true" />

  <!-- Auto-detect from IP address -->
  <MazInputPhoneNumber fetch-country />

  <!-- Set specific default country -->
  <MazInputPhoneNumber
    :use-browser-locale="false"
    country-code="JP"
  />
</template>

Phone Number Formatting

Control how phone numbers are automatically formatted as users type.

Format on Blur (Default)

Shows raw input while typing, formats when field loses focus

Country code

Type freely, formats on blur

Format While Typing

Real-time formatting as you type

Country code

Formats as you type

Disable Formatting

For countries with multiple valid lengths or custom formatting

Country code

Raw input, no formatting

<template>
  <!-- Format on blur (default) - best UX for most cases -->
  <MazInputPhoneNumber auto-format="blur" />

  <!-- Format while typing - immediate visual feedback -->
  <MazInputPhoneNumber auto-format="typing" />

  <!-- Disable formatting - for special cases -->
  <MazInputPhoneNumber auto-format="disabled" />

  <!-- Legacy boolean support (false = disabled, true = typing) -->
  <MazInputPhoneNumber :auto-format="false" />
</template>

Validation States

Control the visual validation feedback and success/error indicators.

Hide Validation UI

No visual success/error indicators

Country code

Phone number

Force Success State

Always show success styling

Country code

Phone number

Force Error State

Always show error styling

Country code

Phone number

<template>
  <!-- Hide validation indicators -->
  <MazInputPhoneNumber
    :validation-success="false"
    :validation-error="false"
  />

  <!-- Force success state -->
  <MazInputPhoneNumber success />

  <!-- Force error state -->
  <MazInputPhoneNumber error />
</template>

Internationalization

Make the component speak your users' language.

Custom Labels

Translate all text in the interface

Select your country

Enter phone number

Country Names in French

Change the language of country names

Country code

Phone number

Custom Country Names

Override specific country names

Country code

Phone number

<template>
  <!-- Custom translations -->
  <MazInputPhoneNumber
    :translations="{
      countrySelect: {
        placeholder: 'Select your country',
        error: 'Please choose a country',
        searchPlaceholder: 'Search countries...'
      },
      phoneInput: {
        placeholder: 'Enter phone number',
        example: 'Format: {example}'
      }
    }"
  />

  <!-- French country names -->
  <MazInputPhoneNumber country-locale="fr-FR" />

  <!-- Custom country names -->
  <MazInputPhoneNumber
    :custom-countries-list="{
      US: 'United States of America',
      GB: 'United Kingdom',
      FR: 'République Française'
    }"
  />
</template>

Custom Flag Styling

Replace the default flag emojis with your own design.

Country Code Badges

Show country codes instead of flags

Country code

Phone number

Custom Icons

Use your own flag icons or designs

Country code

Phone number

<template>
  <!-- Country code badges -->
  <MazInputPhoneNumber>
    <template #selector-flag="{ countryCode }">
      <span class="country-badge">
        {{ countryCode }}
      </span>
    </template>
    <template #country-list-flag="{ countryCode }">
      <MazBadge size="sm" class="me-2">
        {{ countryCode }}
      </MazBadge>
    </template>
  </MazInputPhoneNumber>

  <!-- Custom icons -->
  <MazInputPhoneNumber>
    <template #selector-flag="{ countryCode }">
      <div class="custom-flag-icon">
        {{ countryCode?.charAt(0) }}
      </div>
    </template>
    <template #country-list-flag="{ countryCode }">
      <div class="custom-list-icon">
        {{ countryCode?.charAt(0) }}
      </div>
    </template>
  </MazInputPhoneNumber>
</template>

<style scoped>
@reference "../../.vitepress/theme/main.css";
.country-badge {
  @apply bg-primary text-primary-foreground px-2 py-1 rounded-md text-xs font-semibold;
}

.custom-flag-icon,
.custom-list-icon {
  @apply w-6 h-6 bg-linear-to-r from-blue-500 to-green-500 rounded-full flex items-center justify-center text-white text-xs font-bold;
}

.custom-list-icon {
  @apply me-2;
}
</style>

SVG Flags

You can use libraries like country-flag-icons to display beautiful SVG flags instead of emoji flags.

Advanced Configuration

Fine-tune the component for specific use cases.

Phone-only Mode

Hide country selector, pre-select country

US Phone Number

Custom Search Sensitivity

Adjust how strict country search is (0 = fuzzy, 1 = exact)

Country code

Disable Search

Remove search functionality from country list

Country code

Phone number

Different Dropdown Position

Control where the country list appears

Country code

Phone number

<template>
  <!-- Phone-only mode -->
  <MazInputPhoneNumber
    hide-country-select
    country-code="US"
    :translations="{
      phoneInput: {
        placeholder: 'US Phone Number'
      }
    }"
  />

  <!-- Fuzzy search -->
  <MazInputPhoneNumber :search-threshold="0.3" />

  <!-- No search -->
  <MazInputPhoneNumber :search="false" />

  <!-- Different dropdown position -->
  <MazInputPhoneNumber list-position="top-start" />
</template>

Real-world Examples

See how to use the component in common scenarios.

🏢 Business Form

Perfect for customer registration

Full Name

Email

Country code

Business Phone

🌍 Global Support

Multi-language international form

País

Número de teléfono

📱 Mobile-first Design

Optimized for mobile apps

Country code

Phone number

<script setup>
import { ref } from 'vue'

const businessPhone = ref()
const businessCountry = ref()
const businessResults = ref()

const globalPhone = ref()
const mobilePhone = ref()
</script>

<template>
  <!-- Business form -->
  <div class="form-container">
    <MazInput label="Full Name" placeholder="John Doe" />
    <MazInput label="Email" type="email" placeholder="john@example.com" />
    <MazInputPhoneNumber
      v-model="businessPhone"
      v-model:country-code="businessCountry"
      label="Business Phone"
      :preferred-countries="['US', 'CA', 'GB', 'AU']"
      @data="businessResults = $event"
    />
    <MazBtn color="primary" block>Create Account</MazBtn>
  </div>

  <!-- Global support -->
  <MazInputPhoneNumber
    v-model="globalPhone"
    country-locale="es-ES"
    show-code-in-list
    :translations="{
      countrySelect: {
        placeholder: 'País',
        searchPlaceholder: 'Buscar país...'
      },
      phoneInput: {
        placeholder: 'Número de teléfono'
      }
    }"
  />

  <!-- Mobile-first -->
  <MazInputPhoneNumber
    v-model="mobilePhone"
    orientation="col"
    size="lg"
    fetch-country
    block
  />
</template>

Data Handling

Understanding what data the component provides.

Your phone number

Country code

Enter your phone number in international format (e.g. +33612345678)

<script setup>
import { ref } from 'vue'

const dataPhone = ref()
const dataCountry = ref()
const phoneData = ref()

// Handle the data event
function handlePhoneData(results) {
  console.log('Phone validation results:', results)
  // results contains:
  // - isValid: boolean
  // - countryCode: string
  // - formatNational: string
  // - formatInternational: string
  // - e164: string
  // - type: 'mobile' | 'fixedLine' | etc.
  // - and more...
}
</script>

<template>
  <MazInputPhoneNumber
    v-model="dataPhone"
    v-model:country-code="dataCountry"
    @data="handlePhoneData"
  />
</template>

Troubleshooting

Common issues and solutions:

⚠️ Auto-formatting Issues

For countries like Anguilla (AI) with multiple valid number lengths, disable auto-formatting:

<MazInputPhoneNumber auto-format="disabled" country-code="AI" />

🌐 Country Detection Not Working

Make sure to enable the right detection method:

<!-- Browser locale (default) -->
<MazInputPhoneNumber :use-browser-locale="true" />

<!-- IP-based detection (requires internet) -->
<MazInputPhoneNumber fetch-country />

<!-- Manual fallback -->
<MazInputPhoneNumber country-code="US" />

Types

Results object emitted by @data event:

interface MazInputPhoneNumberData {
  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
}

Tips

TIP

This component use MazInput, so it inherits all his props

Props

Name	Description	Type	Required	Default	Possible values
model-value	v-model The current value of the input field in international format (e.g. +33612345678)	string | null	No	-	-
country-code	v-model:country-code The selected country code (e.g. "FR")	CountryCode | null	No	-	-
id	Unique identifier for the component	string	No	-	-
placeholder	Text displayed when the input is empty	string	No	-	-
top-label	Static label displayed above the input field. Unlike the floating label, this remains fixed	string	No	-	-
label	Label displayed above the input	string	No	-	-
preferred-countries	List of country codes to place first in the select list	CountryCode[]	No	-	-
ignored-countries	List of country codes to be removed from the select list	CountryCode[]	No	-	-
only-countries	List of country codes to only have the countries selected in the select list	CountryCode[]	No	-	-
translations	Locale strings of the component The default values are the translations of the MazUiTranslations plugin	Partial<{ countrySelect: { placeholder: string; error: string; searchPlaceholder: string; }; phoneInput: { placeholder: string; example: string; }; }>	No	{ countrySelect: { error: 'Choose country', placeholder: 'Country code', searchPlaceholder: 'Search the country', }, phoneInput: { placeholder: 'Phone number', example: 'Example: {example}', }, }	-
list-position	Position where the list of countries will be opened	MazPopoverPosition	No	"bottom-start"	'top' | 'left' | 'right' | 'bottom'
color	Component color applied	"primary" | "secondary" | "accent" | "info" | "success" | "warning" | "destructive" | "contrast" | "transparent"	No	"primary"	'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'destructive' | 'contrast' | 'transparent'
size	Component size applied	"xs" | "sm" | "md" | "lg" | "xl" | "mini"	No	"md"	'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'mini'
hide-flags	Remove flags in country list	boolean	No	false	-
flag-src	Source of the flags, instead of the flagcdn.com CDN: a URL template (/flags/{code}.svg, {CODE} for uppercase) or a function giving the image source of a code. Use loadCountryFlag from maz-ui/country-flags for the flags of @maz-ui/icons. Can be set for the whole app with the defaults.global.flagSrc option of the MazUi plugin.	MazCountryFlagSrc	No	undefined (flags from flagcdn.com)	-
disabled	Make the input disabled	boolean	No	false	-
required	Make the input required	boolean	No	false	-
example	Show the phone number example	boolean	No	true	-
search	Disable search input in country list	boolean	No	true	-
search-threshold	Threshold of the search input in country list where 1 is a perfect match and 0 is a match with any character	number	No	0.75	-
use-browser-locale	If true, the browser locale will be used	boolean	No	true	-
fetch-country	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	No	false	-
hide-country-select	Hide the country selector	boolean	No	false	-
show-code-in-list	Show country calling code in the country list	boolean	No	false	-
custom-countries-list	Replace country names	Record<CountryCode, string>	No	-	-
auto-format	Disabled auto-format when phone is valid	false | "disabled" | "blur" | "typing"	No	"blur"	'disabled' | 'blur' | 'typing'
country-locale	Locale of country list	string	No	-	-
validation-error	Disable validation error UI	boolean	No	true	-
validation-success	Disable validation success UI	boolean	No	true	-
success	Add success UI	boolean	No	false	-
error	Add error UI	boolean	No	false	-
warning	Add warning UI	boolean	No	false	-
display-country-name	Will replace the calling code by the country name in the country selector	boolean	No	false	-
block	The input will be displayed in full width	boolean	No	false	-
orientation	Orientation of the inputs in the component	"row" | "col" | "responsive"	No	"responsive"	'row' | 'col' | 'responsive'
country-select-attributes	Meta attributes of the country input	Record<string, unknown>	No	{ name: "country", autocomplete: "off", style: { width: "14rem", }, }	-
phone-input-attributes	Meta attributes of the phone number input	(Record<string, unknown> & { name: string; inputmode: "none" | "text" | "search" | "url" | "email" | "tel" | "numeric" | "decimal" | undefined; autocomplete: string; })	No	{ name: "phone", autocomplete: "tel", inputmode: "tel", }	-
assistive-text	Helper text displayed below the input to provide additional context or validation feedback	string	No	-	-
hint	Alternative text that replaces the label when provided. Useful for contextual hints	string	No	-	-

Events

Event name	Payload	Description
update:model-value	value: string | null | undefined	Emitted when country or phone number changes
data	results: MazInputPhoneNumberData	Emitted when country or phone number changes
country-code	countryCode?: CountryCode | null | undefined	Emitted when selected country changes
update:country-code	countryCode?: CountryCode | null | undefined	Emitted when country changes

Slots

Name	Description	Bindings
no-results	Replace the "no results" icon in the country selector list	-
selector-flag	Country selector flag	countryCode CountryCode - current selected country code Ex: "FR"
country-list-flag	Country list flag	countryCode CountryCode - country code of option Ex: "FR" option CountryOption - country data isSelected boolean - true if option is selected