Phone Field

Phone number field with consumer-supplied country metadata, pattern formatting, and E.164 output.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/ui

Add the public import below to <script setup lang="ts">. Components provide behavior without styles; the preview uses optional Paper styles.

import { PhoneField, PhoneFieldInput, PhoneFieldCountrySelect } from "@vizejs/ui/phone-field";

Or copy the source into your project with vize lib pull phone-field (see Source Distribution).

Try it

This is the basic example maintained with the component source, using the public package imports. The preview adds the optional Paper styles.

Open the interactive example · Styling these components

Copy the example

<!-- Phone number field bound with v-model to an E.164 value, with a country select and pattern formatting. -->
<script setup lang="ts">
import { ref, useId } from "vue";

import {
  PhoneField,
  PhoneFieldCountrySelect,
  PhoneFieldInput,
  definePhoneCountries,
} from "@vizejs/ui/phone-field";

const countries = definePhoneCountries([
  { code: "JP", name: "Japan", dialCode: "81", pattern: "99-9999-9999", trunkPrefix: "0" },
  { code: "US", name: "United States", dialCode: "1", pattern: "(999) 999-9999" },
  { code: "GB", name: "United Kingdom", dialCode: "44", pattern: "9999 999999", trunkPrefix: "0" },
]);

const phone = ref("");
const inputId = useId();
</script>

<template>
  <div>
    <label :for="inputId">Mobile number</label>
    <PhoneField
      :id="inputId"
      v-slot="{ international }"
      v-model="phone"
      :countries
      default-country="JP"
      name="phone"
      required
    >
      <PhoneFieldCountrySelect />
      <PhoneFieldInput autocomplete="tel-national" />
      <output>{{ international }}</output>
    </PhoneField>
  </div>
</template>

API

PhoneField<Code extends string>

Source: src/families/form/phone-field/phone-field.vue

Props

Events

Slots

Exposed

PhoneFieldInput

Source: src/families/form/phone-field/phone-field-input.vue

Props

PhoneFieldCountrySelect

Source: src/families/form/phone-field/phone-field-country-select.vue

Props

Behavior

Normative state x input -> outcome table for phone-field.vue, phone-field-input.vue, and phone-field-country-select.vue (@vizejs/ui/phone-field). No country data is bundled: consumers pass countries (typed with definePhoneCountries), whose code literals type v-model:country. Formatting reuses the input-mask engine; the country picker reuses NativeSelect. Every row is proven by the named test in phone-field.test.ts or phone-field-ssr.test.ts; compile-only assertions live in phone-field.types.test-d.ts.

Public extension contract

The subpath is tree-shakable and ships no CSS; those package contracts are pinned by distribution.test.ts, check:size, and check:tree-shaking.