Cleave.js — Format Input Text as You Type

Introduction

Cleave.js solves the common UX problem of formatting user input in real time. Instead of validating and reformatting after submission, it formats credit card numbers, phone numbers, dates, numerals, and custom patterns as the user types. This gives users immediate visual feedback, reduces errors, and eliminates the need for separate formatting logic.

What Cleave.js Does

• Formats credit card numbers with automatic card type detection (Visa, Mastercard, Amex, etc.)
• Formats phone numbers by region using Google's libphonenumber
• Formats dates with configurable patterns like MM/DD/YYYY or YYYY-MM-DD
• Formats numerals with thousands separators, decimal scales, and prefix/suffix
• Supports custom delimiters and block patterns for arbitrary formatting

Architecture Overview

Cleave.js attaches to an input element and intercepts keystrokes via input event listeners. It maintains an internal formatter that applies the configured pattern rules to the raw value, calculating cursor position to keep the caret in the correct location after reformatting. The library is written in vanilla JavaScript with no dependencies and is distributed as both CommonJS and ES modules. React and Angular wrappers are provided as separate packages.

Self-Hosting & Configuration

• Install via npm or include the script tag from a CDN
• Create a new Cleave instance passing a CSS selector and an options object
• For credit cards, set creditCard: true and listen to onCreditCardTypeChanged
• For phone numbers, import the phone addon for your region and set phone: true
• For custom patterns, use blocks, delimiters, and numericOnly options

Key Features

• Automatic credit card type detection with brand-specific formatting
• Phone formatting powered by Google libphonenumber for 200+ regions
• Date formatting with min/max date validation
• Numeral formatting with configurable thousands separator and decimal mark
• Raw value access via getRawValue() for form submission without formatting characters

Comparison with Similar Tools

• Inputmask — more comprehensive masking library with regex support; Cleave.js focuses on common patterns with a simpler API
• IMask — flexible masking with pipe and pattern support; Cleave.js is more opinionated and quicker to set up
• vanilla-masker — lightweight alternative but less maintained
• Native pattern attribute — only validates on submit; Cleave.js formats in real time

FAQ

Q: How do I get the unformatted value for form submission? A: Call cleaveInstance.getRawValue() to retrieve the value without delimiters and formatting characters.

Q: Does it work with React? A: Yes. Install cleave.js and use the provided React component import Cleave from 'cleave.js/react', or use it with refs in a useEffect hook.

Q: Can I customize the formatting pattern? A: Yes. Use the blocks array to define segment lengths and delimiters to specify separator characters between blocks.

Q: Does it handle paste events? A: Yes. Pasted text is automatically reformatted according to the configured pattern.

Sources

• https://github.com/nosir/cleave.js
• https://nosir.github.io/cleave.js