🎯 Why Phone Mask?

🔄 Always Up-to-Date

Phone formats sync automatically from Google's libphonenumber — no stale data, no manual updates. Just upgrade and you're current with global dialing rules.

🪶 Lightest in Class

Real market comparison, segmented by ecosystem and measured for what developers actually ship. Snapshot: 2026-03-27 (Bundlephobia API, Bundlephobia Exports API, npm Registry API).

Use Total gzip as the primary comparison column. Gzip is Bundlephobia raw package gzip. Data overhead is additional phone-data gzip excluded from raw package gzip (e.g. required peer engines). When available, export-level Bundlephobia sizes are used for better precision. Total gzip = Gzip + Data overhead.

Core (TypeScript/JavaScript)

Best choice in Core (TypeScript/JavaScript): @desource/phone-mask (5.1 KB).

React

Best choice in React: @desource/phone-mask-react (9.2 KB).

React ecosystem note: react-international-phone removed built-in validation in v3 and recommends adding google-libphonenumber separately (migration doc). Raw package gzip above does not include that optional validator overhead.

Vue

Best choice in Vue: @desource/phone-mask-vue (10.5 KB).

Svelte

Best choice in Svelte: @desource/phone-mask-svelte (11.1 KB).

Nuxt

Best choice in Nuxt: @desource/phone-mask-nuxt (10.9 KB).

Nuxt ecosystem note: there are currently no widely adopted Nuxt-only phone input modules with stable npm + Bundlephobia signals comparable to React/Vue/Svelte peers; most Nuxt apps use Vue phone input packages directly.

🎨 Framework-Ready

Ready-made plugins for your stack:

• ✅ Vue 3 — Component, composable, and directive
• ✅ Nuxt — Auto-imported, SSR-compatible
• ✅ React — Component & hook with modern React patterns
• ✅ Svelte — Component, composable, action, and attachment for Svelte 5
• ✅ TypeScript/Vanilla JS — Framework-agnostic core

📦 Packages

Package	Version	Description
@desource/phone-mask		Core library — TypeScript/JS
@desource/phone-mask-react		React component + hook
@desource/phone-mask-vue		Vue 3 component + composable + directive
@desource/phone-mask-svelte		Svelte 5 component + composable + action + attachment
@desource/phone-mask-nuxt		Nuxt module

⚡ Quick Start

React

npm install @desource/phone-mask-react

import { useState } from 'react';
import { PhoneInput } from '@desource/phone-mask-react';
import '@desource/phone-mask-react/assets/lib.css';

function App() {
  const [phone, setPhone] = useState('');

  return <PhoneInput value={phone} onChange={setPhone} country="US" />;
}

Vue 3

npm install @desource/phone-mask-vue

<script setup>
import { ref } from 'vue';
import { PhoneInput } from '@desource/phone-mask-vue';
import '@desource/phone-mask-vue/assets/lib.css';

const phone = ref('');
</script>

<template>
  <PhoneInput v-model="phone" country="US" />
</template>

Svelte 5

npm install @desource/phone-mask-svelte

<script lang="ts">
import { PhoneInput } from '@desource/phone-mask-svelte';
import '@desource/phone-mask-svelte/assets/lib.css';

let phone = $state('');
</script>

<PhoneInput bind:value={phone} country="US" />

Nuxt

npm install @desource/phone-mask-nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@desource/phone-mask-nuxt']
});

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

const phone = ref('');
</script>

<template>
  <PhoneInput v-model="phone" country="US" />
</template>

TypeScript/Vanilla JS

npm install @desource/phone-mask

import { MasksFullMapEn, formatDigitsWithMap } from '@desource/phone-mask';

const mask = MasksFullMapEn.US.mask[0]; // "###-###-####"
const formatted = formatDigitsWithMap(mask, '2025551234').display;
// Result: "202-555-1234"

✨ Features

• 🌍 240+ countries with accurate dialing codes and formats
• 🎭 Auto-formatting as you type with smart cursor positioning
• 🔍 Country search with fuzzy matching and keyboard navigation
• 🌐 Auto-detection via GeoIP and browser locale
• 📋 Copy to clipboard with one click
• ✨ Validation with visual feedback
• 🎨 Themeable (light/dark) with custom styling
• ♿ Accessible with ARIA labels and keyboard support
• 📱 Mobile-optimized with proper input modes
• 🌳 Tree-shakeable — only import what you use
• 🔧 TypeScript — full type safety
• 🧩 Directive mode for custom input styling

🎮 Demo

Live Demo →

Try the interactive playground with:

• Real-time formatting preview
• Country switching
• Theme toggle
• Code examples

📚 Documentation

• Core
• React
• Vue
• Nuxt
• Svelte

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Contribution Flow

1. Fork the repository
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/phone-mask.git
3. Install dependencies: pnpm install
4. Create a branch: git checkout -b feature/my-feature
5. Make your changes
6. Commit: git commit -m "feat: add awesome feature"
7. Push: git push origin feature/my-feature
8. Open a Pull Request

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run unit tests with coverage report
pnpm test:unit:coverage

# Start demo dev server
pnpm dev:prepare
pnpm dev:demo

# Generate fresh data from Google's library
pnpm gen

🌟 Sponsors

Developed and maintained by DeSource Labs.

Created by Stefan Popov

📄 License

MIT © 2026 DeSource Labs

🔗 Links

• npm Registry
• GitHub Organization
• Issue Tracker
• Discussions