nosir/cleave.js · error · Error

[cleave.js] Please include phone-type-formatter.{country}.js

Error message

[cleave.js] Please include phone-type-formatter.{country}.js lib

What it means

When `phone: true` is set, Cleave instantiates an AsYouTypeFormatter from the per-country libphonenumber addon script on `pps.root.Cleave`. If that addon file was not loaded, the constructor throws and Cleave replaces it with this clearer message at src/Cleave.js:165.

Source

Thrown at src/Cleave.js:165

        pps.maxLength = Cleave.Util.getMaxLength(pps.blocks);
    },

    initPhoneFormatter: function () {
        var owner = this, pps = owner.properties;

        if (!pps.phone) {
            return;
        }

        // Cleave.AsYouTypeFormatter should be provided by
        // external google closure lib
        try {
            pps.phoneFormatter = new Cleave.PhoneFormatter(
                new pps.root.Cleave.AsYouTypeFormatter(pps.phoneRegionCode),
                pps.delimiter
            );
        } catch (ex) {
            throw new Error('[cleave.js] Please include phone-type-formatter.{country}.js lib');
        }
    },

    onKeyDown: function (event) {
        var owner = this,
            charCode = event.which || event.keyCode;

        owner.lastInputValue = owner.element.value;
        owner.isBackward = charCode === 8;
    },

    onChange: function (event) {
        var owner = this, pps = owner.properties,
            Util = Cleave.Util;

        owner.isBackward = owner.isBackward || event.inputType === 'deleteContentBackward';

        var postDelimiter = Util.getPostDelimiter(owner.lastInputValue, pps.delimiter, pps.delimiters);

View on GitHub (pinned to a966c95cf5)

Solutions

1. Import the matching addon before constructing: require/import 'cleave.js/dist/addons/phone-type-formatter.{country}.js'.
2. Confirm the addon registers Cleave.AsYouTypeFormatter on the same global root Cleave uses (browser: window.Cleave).
3. If phone formatting is not needed, remove phone:true / phoneRegionCode from the options.
4. With a bundler, ensure the addon side-effect import is not tree-shaken.

Example fix

// before
const Cleave = require('cleave.js');
new Cleave(el, { phone: true, phoneRegionCode: 'US' });
// after
const Cleave = require('cleave.js');
require('cleave.js/dist/addons/phone-type-formatter.us.js');
new Cleave(el, { phone: true, phoneRegionCode: 'US' });

if (typeof window.Cleave === 'undefined' || typeof window.Cleave.AsYouTypeFormatter !== 'function') {
  throw new Error('Load phone-type-formatter.{country}.js before phone formatting');
}

function hasPhoneAddon(root) {
  return !!(root && root.Cleave && typeof root.Cleave.AsYouTypeFormatter === 'function');
}

try {
  new Cleave(el, { phone: true, phoneRegionCode: 'US' });
} catch (e) {
  if (e.message.includes('phone-type-formatter')) {
    console.warn('Phone addon missing; init without phone formatting');
    new Cleave(el, {});
  } else { throw e; }
}

When it happens

Trigger: new Cleave(el, { phone: true, phoneRegionCode: 'US' }) without first loading dist/addons/phone-type-formatter.us.js (or the equivalent script) into the same global root.

Common situations: Using the npm module without importing the addon file; bundler tree-shaking out the addon; loading the addon on a different global (window vs module scope); missing region-specific file for an uncommon country.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Please include phone-type-formatter.{country}.js lib
• Invalid region code:
• Invalid region code:
• Invalid region code:
• Invalid region code:

AI-assisted analysis of nosir/cleave.js@a966c95cf5 (2026-09-02). Data as JSON: /api/errors/9046d4106526d922. Report an issue: GitHub.