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

✨ 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 { MazInputPhoneNumber } from 'maz-ui'
import { ref } from 'vue'

const phoneNumber = ref()
const countryCode = ref()
const results = ref()
</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

Show your most common countries first

Country code

Only Specific Countries

Limit to certain countries only

Country code

Ignore Countries

Remove unwanted countries

Country code

<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 (Default)

Stacks on mobile, side-by-side on desktop

Country code

Phone number

Always Row

Side-by-side on all screen sizes

Country code

Phone number

Always Column

Stacked on all screen sizes

Country code

Phone number

<template>
  <!-- Responsive layout (default) -->
  <MazInputPhoneNumber orientation="responsive" />

  <!-- Always side-by-side -->
  <MazInputPhoneNumber orientation="row" />

  <!-- Always stacked -->
  <MazInputPhoneNumber orientation="col" />
</template>

Display Options

Customize what information is shown to users.

Show Country Names

Display country names instead of calling codes

Choose country

Phone number

Show Calling Codes in List

Help users see the dialing codes

Country code

Phone number

Hide Phone Examples

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

Country code

Phone number

Hide Country Flags

Text-only country selection

Country code

Phone number

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

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="maz-mr-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>
.country-badge {
  @apply maz-bg-primary maz-text-primary-foreground maz-px-2 maz-py-1 maz-rounded maz-text-xs maz-font-semibold;
}

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

.custom-list-icon {
  @apply maz-mr-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.

Country code

Enter a phone number to see data

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

Props

Name	Description	Type	Required	Default	Possible values
style	Style attribut of the component root element	HTMLAttributes['style']	No	undefined	-
class	Class attribut of the component root element	HTMLAttributes['class']	No	undefined	-
model-value	v-model The current value of the input field in international format (e.g. +33612345678) Example: "+33612345678"	string | undefined | null	No	undefined	-
country-code	v-model:country-code The selected country code (e.g. "FR") Example: "FR"	CountryCode | undefined | null	No	undefined	-
id	Unique identifier for the component Example: "phone-input-1"	string	No	undefined	-
placeholder	Text displayed when the input is empty Example: "Enter your phone number"	string	No	undefined	-
label	Label displayed above the input Example: "Phone Number"	string	No	undefined	-
preferred-countries	List of country codes to place first in the select list Example: ["FR", "BE", "GE"]	CountryCode[]	No	undefined	-
ignored-countries	List of country codes to be removed from the select list Example: ["FR", "BE", "GE"]	CountryCode[]	No	undefined	-
only-countries	List of country codes to only have the countries selected in the select list Example: ["FR", "BE", "GE"]	CountryCode[]	No	undefined	-
translations	Locale strings of the component The default values are the translations of the MazUiTranslations plugin	Partial<MazUiTranslationsNestedSchema['inputPhoneNumber']>	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	MazPopoverProps['position']	No	'bottom-start'	top left, top right, bottom left, bottom right
color	Component color applied	MazColor	No	'primary'	primary, secondary, accent, info, success, warning, destructive, contrast
size	Component size applied	MazSize	No	'md'	xs, sm, md, lg, xl, mini
hide-flags	Remove flags in country list	boolean	No	false	-
disabled	Disable input	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	undefined	-
auto-format	Disabled auto-format when phone is valid	"blur" | "typing" | "disabled" | false	No	'blur'	-
country-locale	Locale of country list Example: "fr-FR"	string	No	undefined	-
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	-
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>	No	() => ({ 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
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