cleave.js

What is cleave.js?

Cleave.js is a JavaScript library that helps you format input fields in real-time. It provides a simple way to format various types of input fields such as credit card numbers, phone numbers, dates, and more.

What are cleave.js's main functionalities?

Credit Card Number Formatting

This feature automatically formats credit card numbers as the user types. It adds spaces between every four digits for better readability.

new Cleave('.input-credit-card', { creditCard: true });

Phone Number Formatting

This feature formats phone numbers according to the specified region code. In this example, it formats phone numbers in the US format.

new Cleave('.input-phone', { phone: true, phoneRegionCode: 'US' });

Date Formatting

This feature formats date inputs according to the specified pattern. In this example, it formats the date in the 'YYYY-MM-DD' format.

new Cleave('.input-date', { date: true, datePattern: ['Y', 'm', 'd'] });

Numeral Formatting

This feature formats numerical inputs with thousand separators. It makes large numbers more readable by adding commas.

new Cleave('.input-numeral', { numeral: true, numeralThousandsGroupStyle: 'thousand' });

Custom Delimiter

This feature allows custom delimiters and block sizes for input formatting. In this example, it formats the input with dashes every four characters.

new Cleave('.input-custom', { delimiter: '-', blocks: [4, 4, 4, 4] });

Other packages similar to cleave.js

inputmask

Inputmask is a JavaScript library that creates input masks for various types of input fields. It is highly configurable and supports a wide range of input types. Compared to Cleave.js, Inputmask offers more customization options but may require more configuration.

vanilla-text-mask

Vanilla Text Mask is a library for creating input masks in vanilla JavaScript. It is lightweight and easy to use, similar to Cleave.js. However, it may not offer as many built-in formatting options as Cleave.js.

imask

IMask is a versatile input masking library that supports a wide range of input types and custom masks. It is similar to Cleave.js in terms of functionality but offers more advanced features like dynamic masks and pattern matching.

README

Cleave.js

Cleave.js has a simple purpose: to help you format input text content automatically.

Features

• Credit card number formatting
• Phone number formatting (i18n js lib separated for each country to reduce size)
• Date formatting
• Numeral formatting
• Custom delimiter, prefix and blocks pattern
• CommonJS / AMD mode
• ReactJS component
• AngularJS directive (1.x)

TL;DR the demo page

Why?

The idea is to provide an easy way to increase input field readability by formatting your typed data. By using this library, you won't need to write any mind-blowing regular expressions or mask patterns to format input text.

However, this isn't meant to replace any validation or mask library, you should still sanitize and validate your data in backend.

Installation

npm

npm install --save cleave.js

old school

Grab file from dist directory

Usage

Simply include

<script src="cleave.min.js"></script>
<script src="cleave-phone.{country}.js"></script>

cleave-phone.{country}.js addon is only required when phone shortcut mode is enabled. See more in documentation: phone lib addon section

Then have a text field

<input class="input-phone" type="text"/>

Now in your JavaScript

var cleave = new Cleave('.input-element', {
    phone: true,
    phoneRegionCode: '{country}'
});

.input-element here is a unique DOM element. If you want to apply Cleave for multiple elements, you need to give different css selectors and apply to each of them

More examples: the demo page

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(...)
});

ReactJS component usage

import React from 'react';
import ReactDOM from 'react-dom';

import Cleave from 'cleave.js/react';

Then in JSX:

class MyComponent extends React.Component {

    constructor(props, context) {
        super(props, context);
        this.onCreditCardChange = this.onCreditCardChange.bind(this);
        this.onCreditCardFocus = this.onCreditCardFocus.bind(this);
    }

    onCreditCardChange(event) {
        // formatted pretty value
        console.log(event.target.value);

        // raw value
        console.log(event.target.rawValue);
    }

    onCreditCardFocus(event) {
        // update some state
    }

    render() {
        return (
            <Cleave placeholder="Enter your credit card number"
                options={{creditCard: true}}
                onFocus={this.onCreditCardFocus}
                onChange={this.onCreditCardChange} />
        );
    }
}

As you can see, here you simply use <Cleave/> as a normal <input/> field

• Attach HTML <input/> attributes
• Pass in the custom options prop
• Add ReactJS onChange event listener

Advanced usage:

• How to pass default value
• How to call to update raw value
• How to get ref of the input field

Usage for Webpack, Browserify and more in documentation: ReactJS component usage

AngularJS directive usage

First include the directive module:

<script src="cleave.js/dist/cleave-angular.min.js"></script>
<script src="cleave.js/dist/addons/cleave-phone.{country}.js"></script>

And in your model:

angular.module('app', ['cleave.js'])

.controller('AppController', function($scope) {
    $scope.onCreditCardTypeChanged = function(type) {
        $scope.model.creditCardType = type;
    };

    $scope.model = {
        rawValue: ''
    };

    $scope.options = {
        creditCard: {
            creditCard: true,
            onCreditCardTypeChanged: $scope.onCreditCardTypeChanged
        }
    };
});

Then easily you can apply cleave directive to input field:

<div ng-controller="AppController">
    <input ng-model="model.rawValue" ng-whatever="..." type="text" placeholder="Enter credit card number"
        cleave="options.creditCard"/>
</div>

More usage in documentation: Angular directive usage

Playground

• Plain JSFiddle (Basic usage)
• Plain JSFiddle (More examples)
• React JSFiddle
• Angular JSFiddle

Documentation

• JavaScript API
  • Constructor
  • Options
  • Public methods
• Phone lib addon
• ReactJS component usage
• AngularJS directive usage

Run tasks

npm install

Build assets

gulp build

Run tests

gulp test

Lint

gulp eslint

Publish (build, tests & lint)

gulp publish

For contributors, please run gulp publish to ensure your PR passes tests and lint, also we have a not in the plan list you may concern.

Get in touch

• Twitter: @rison

References

• Payment credit card number IIN https://en.wikipedia.org/wiki/Payment_card_number#Issuer_identification_number_.28IIN.29
• Google phone numbers formatting https://github.com/googlei18n/libphonenumber
• Decimal mark and thousands separating style https://en.wikipedia.org/wiki/Decimal_mark#Examples_of_use

Licence

Cleave.js is licensed under the Apache License Version 2.0

• Google libphonenumber is included under its Apache License Version 2.0