Cleave.js

IMPORTANT

Cleave.js is deprecated.

If you are starting a new project or looking to upgrade, please use the new version: cleave-zen.

If your application needs to support multiple countries, do not include multiple individual country scripts (e.g., <script src="cleave-phone.ca.js"></script> and <script src="cleave-phone.us.js"></script>). This is inefficient.

Instead, you should build a custom combination library (e.g., (US & CA).js) that contains only the required country metadata. To build your own combination, refer to the libphonenumber-country-metadata build guide.

The Cleave component is primarily an uncontrolled component. Do not attempt to bind the value attribute to a React state variable for data binding, as this can cause unexpected behavior.

To programmatically update the input value, use the onInit pattern to get the Cleave instance and call cleave.setRawValue('...').

// Correct way to update value:
this.state.cleaveInstance.setRawValue('new-raw-value');

Import the core React component from cleave.js/react. For phone formatting, import specific country addons.

Important: When importing phone addons, the {country} code must be in lowercase (e.g., pt for Portugal), which differs from the phoneRegionCode option used in the component props.

import React from 'react';
import Cleave from 'cleave.js/react';
import CleavePhone from 'cleave.js/dist/addons/cleave-phone.pt';

In AMD environments, include both the core library and the country addon in the dependency array.

require(['dist/cleave.min', 'dist/addons/cleave-phone.{country}'], function (Cleave) {
    var cleave = new Cleave(...)
});

Cleave.js supports multiple module formats for integration into modern build pipelines.

// CommonJS
var Cleave = require('cleave.js');
require('cleave.js/dist/addons/cleave-phone.{country}');
var cleave = new Cleave(...);

// AMD
require(['cleave.js/dist/cleave.min', 'cleave.js/dist/addons/cleave-phone.{country}'], function (Cleave) {
    var cleave = new Cleave(...);
});

// ES Module (Rollup, Webpack)
import Cleave from 'cleave.js';
var cleave = new Cleave(...);

// ES Module (Browser)
import Cleave from 'node_modules/cleave.js/dist/cleave-esm.min.js';
var cleave = new Cleave(...);

Since Cleave.js does not have official Vue.js support, you can register it as a global directive. This allows you to use the v-cleave directive on any input element throughout your application. The directive initializes a new Cleave instance when the element is inserted and synchronizes the formatted value back to the input during updates by dispatching an input event.

import Vue from 'vue'
import Cleave from 'cleave.js';

Vue.directive('cleave', {
    inserted: (el, binding) => {
        el.cleave = new Cleave(el, binding.value || {})
    },
    update: (el) => {
        const event = new Event('input', {bubbles: true});
        setTimeout(function () {
            el.value = el.cleave.properties.result
            el.dispatchEvent(event)
        }, 100);
    }
})

To use Cleave.js in a standard web environment, include the script and then instantiate the Cleave class by passing a unique DOM element selector and an options object.

Note: If you want to apply Cleave to multiple elements, you must create individual instances for each element (e.g., using a loop) rather than passing a single selector that matches multiple elements.

<!-- 1. Include the script -->
<script src="cleave.min.js"></script>

<!-- 2. Create a text field -->
<input class="input-phone" type="text" />

<script>
// 3. Initialize Cleave
var cleave = new Cleave('.input-phone', {
  phone: true,
  phoneRegionCode: '{country}',
})
</script>

To access Cleave's public methods (like setRawValue), you must capture the Cleave instance using the onInit callback. Store this instance in your component's state or a variable.

// 1. Define the init handler
onCreditCardInit(cleave) {
    this.setState({creditCardCleave: cleave});
}

// 2. Pass it to the component
<Cleave options={{creditCard: true}} onInit={this.onCreditCardInit} />

// 3. Use the instance later
this.state.creditCardCleave.setRawValue('123456789');

To access the Cleave instance and call its public methods (like getISOFormatDate()), use the onInit callback option. The directive passes the Cleave instance as a parameter to this callback. You can then store this instance on your $scope to use it elsewhere in your controller.

// In your controller
$scope.onInit = function(cleave) {
    $scope.model.cleave = cleave;
};

$scope.options = {
    onInit: $scope.onInit
};

<input ng-model="model.rawValue" type="text" cleave="options" />