📱 Phone Mask

Always-fresh, extreme small & easy-to-use international phone masking with Google's libphonenumber data

Quick Start • Packages • Features • Demo • Contributing

---

🎯 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

13 KB total (4 KB gzipped) with full tree-shaking support. Compare to alternatives:

Library	Bundle Size (minified)	Gzipped
@desource/phone-mask	13 KB	4 KB
react-phone-input-2	~80 KB	~25 KB
react-phone-number-input	~40 KB	~15 KB
intl-tel-input	~180 KB	~55 KB

🎨 Framework-Ready

Ready-made plugins for your stack:

• ✅ Vue 3 — Composition API component + directive
• ✅ Nuxt — Auto-imported, SSR-compatible
• ✅ TypeScript/Vanilla JS — Framework-agnostic core
• 🔜 React — Coming soon

---

📦 Packages

Package	Version	Description
@desource/phone-mask		Core library — TypeScript/JS
@desource/phone-mask-vue		Vue 3 component + directive
@desource/phone-mask-nuxt		Nuxt module

---

⚡ Quick Start

Vue 3

npm install @desource/phone-mask-vue

<script setup>
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>

Nuxt

npm install @desource/phone-mask-nuxt

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

<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; // "+1 ###-###-####"
const formatted = formatDigitsWithMap(mask, '2025551234');
// Result: "+1 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

• Vue

• Nuxt

---

🤝 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

# Start demo dev server
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 © 2025 DeSource Labs

---

🔗 Links

• npm Registry
• GitHub Organization
• Issue Tracker
• Discussions

---

_{Built with ❤️ by the DeSource Labs team}