A headless library for international phone inputs

Yallison Reis — Sun, 08 Mar 2026 20:06:18 +0000

International phone inputs are surprisingly tricky to implement
correctly.

Formatting, validation, country detection, and handling edge cases can
quickly become complex when building phone input fields for different
regions.

Over the weekend, I built a small open-source library to experiment with
a different approach: a headless engine that handles parsing, masking,
and validation of international phone numbers while leaving the UI
completely up to the developer.

The core is powered by libphonenumber-js and exposes a deterministic
state object that can be used with any framework.

Main ideas behind the project:

Headless architecture (no UI components)
Smart masking based on libphonenumber
Country auto-detection while typing
Deterministic state output
Works with React, React Native, Vue, Angular or vanilla JavaScript

Example usage:

import { IntlPhoneCore, applyClampedValue } from '@intl-phone-js/core';

const phone = new IntlPhoneCore();

input.addEventListener('input', (e) => { 
    const state = applyClampedValue(phone, e.target.value); console.log(state); 
});

Links:

Documentation: https://ygreis.github.io/dev-hub/lib/intl-phone-js-core

GitHub Repository: https://github.com/ygreis/intl-phone-js

NPM: https://www.npmjs.com/package/@intl-phone-js/core

I’d love to hear feedback from anyone who has worked with phone input
libraries before.

Forem: Yallison Reis

A headless library for international phone inputs