Nuxt UI inspired

Phone input for Nuxt apps that want a native-feeling API.

nuxt-phone-number gives you an auto-imported UPhoneInput, a global phoneInput config, and a usePhone() composable for formatting, validation and parsing. The API is shaped to feel close to Nuxt UI component conventions.

UPhoneInput usePhone() Nuxt config SSR-aware

Phone

🇸🇳 +221

77 123 45 67

Variant outline, size md, rounded lg, color primary

Installation

Install the module and register it in your Nuxt config.

Install

npm install nuxt-phone-number libphonenumber-js

Usage

After adding the module, UPhoneInput is available everywhere without manual imports.

Basic

<script setup lang="ts">
const phone = ref("")
</script>

<template>
  <UPhoneInput
    v-model="phone"
    color="primary"
    variant="outline"
    size="md"
    rounded="lg"
  />
</template>

Examples

Common combinations inspired by the Nuxt UI Input API.

Subtle

Use variant="subtle" for calmer forms and dashboards with softer surfaces.

<UPhoneInput
  color="info"
  variant="subtle"
  size="sm"
/>

Soft

Use variant="soft" when you want more visual separation without a heavy outline.

<UPhoneInput
  color="success"
  variant="soft"
  rounded="xl"
/>

Ghost / none

Fit minimalist layouts or custom wrappers with ghost and none.

<UPhoneInput
  color="neutral"
  variant="ghost"
  size="xs"
/>

Nuxt Config

Set defaults once for the whole application.

nuxt.config.ts

export default defineNuxtConfig({
  modules: ["nuxt-phone-number"],

  phoneInput: {
    defaultCountry: "SN",
    preferredCountries: ["SN", "FR"],
    format: "international",
    ui: {
      color: "primary",
      variant: "outline",
      size: "md",
      rounded: "lg"
    }
  }
})

Props

The component supports a Nuxt-UI-like visual API alongside phone input specific options.

Prop	Type	Default
`color`	`"primary" \| "secondary" \| "success" \| "info" \| "warning" \| "error" \| "neutral"`	`"primary"`
`variant`	`"outline" \| "soft" \| "subtle" \| "ghost" \| "none"`	`"outline"`
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`
`rounded`	`"none" \| "sm" \| "md" \| "lg" \| "xl" \| "full"`	`"lg"`
`format`	`"national" \| "international" \| "e164"`	`"international"`
`preferredCountries`	`string[]`	`[]`
`onlyCountries`	`string[]`	`[]`
`ignoredCountries`	`string[]`	`[]`
`error`	`string \| boolean`	`undefined`

Events

Useful outputs for forms, validation and persistence.

Event	Payload	Description
`update:modelValue`	`string`	Current formatted value according to the chosen output mode.
`update:countryCode`	`CountryCode`	Selected country code.
`data`	`PhoneInputData`	Normalized payload with E.164, formatted output and validity.

usePhone

Access formatting and validation helpers from anywhere.

Composable

<script setup lang="ts">
const { formatPhone, validatePhone, parsePhone, defaults } = usePhone()

const formatted = formatPhone("+221771234567")
const valid = validatePhone("+221771234567")
const parsed = parsePhone("+221771234567")
</script>