or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

angular-integration.mdindex.mdphone-formatting.mdreact-integration.mdvanilla-javascript.md
tile.json

tessl/npm-cleave-js

JavaScript library for formatting input text content when you are typing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/cleave.js@1.6.x

To install, run

npx @tessl/cli install tessl/npm-cleave-js@1.6.0

index.mddocs/

Cleave.js

Cleave.js is a JavaScript library for formatting input text content as users type. It provides automatic formatting for credit cards, phone numbers (with internationalization), dates, times, numerals, and custom patterns. The library offers seamless integration with vanilla JavaScript, React components, and AngularJS directives.

Package Information

  • Package Name: cleave.js
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install cleave.js

Core Imports

ES Modules

import Cleave from 'cleave.js';

CommonJS

const Cleave = require('cleave.js');

UMD (Browser)

<script src="cleave.js"></script>
<!-- Available as global Cleave -->

React Component

import Cleave from 'cleave.js/react';

Angular Directive

angular.module('myApp', ['cleave.js']);

Basic Usage

import Cleave from 'cleave.js';

// Credit card formatting
const creditCardInput = new Cleave('#credit-card', {
  creditCard: true,
  onCreditCardTypeChanged: function (type) {
    console.log('Card type:', type);
  }
});

// Phone number formatting
const phoneInput = new Cleave('#phone', {
  phone: true,
  phoneRegionCode: 'US'
});

// Custom formatting with blocks
const customInput = new Cleave('#custom', {
  blocks: [4, 4, 4, 4],
  delimiter: '-',
  uppercase: true
});

// Get values
console.log(creditCardInput.getRawValue()); // Raw unformatted value
console.log(creditCardInput.getFormattedValue()); // Formatted display value

Architecture

Cleave.js is built around several key components:

  • Core Constructor: Main Cleave class that handles input formatting and event management
  • Formatter Classes: Specialized formatters for different data types (numeral, date, time, phone)
  • Framework Integrations: React component and Angular directive wrappers
  • Phone Addons: Country-specific phone formatting modules (247 countries supported)
  • Utility Functions: Helper functions for text processing and cursor management

Capabilities

Vanilla JavaScript Integration

Core Cleave constructor and instance methods for vanilla JavaScript applications. Handles all formatting types and provides complete control over input behavior.

/**
 * Construct a new Cleave instance
 * @param element - CSS selector string, HTMLElement, or NodeList
 * @param options - Configuration options object
 */
constructor Cleave(element: string | HTMLElement | NodeList, options: CleaveOptions);

interface CleaveOptions {
  // Credit card options
  creditCard?: boolean;
  creditCardStrictMode?: boolean;
  onCreditCardTypeChanged?: (type: string) => void;
  
  // Phone options  
  phone?: boolean;
  phoneRegionCode?: string;
  
  // Date options
  date?: boolean;
  datePattern?: string[];
  dateMin?: string;
  dateMax?: string;
  
  // Time options
  time?: boolean;
  timePattern?: string[];
  timeFormat?: string;
  
  // Numeral options
  numeral?: boolean;
  numeralDecimalMark?: string;
  numeralIntegerScale?: number;
  numeralDecimalScale?: number;
  numeralThousandsGroupStyle?: 'thousand' | 'lakh' | 'wan' | 'none';
  numeralPositiveOnly?: boolean;
  stripLeadingZeroes?: boolean;
  signBeforePrefix?: boolean;
  tailPrefix?: boolean;
  
  // General formatting
  blocks?: number[];
  delimiter?: string;
  delimiters?: string[];
  delimiterLazyShow?: boolean;
  prefix?: string;
  noImmediatePrefix?: boolean;
  rawValueTrimPrefix?: boolean;
  copyDelimiter?: boolean;
  
  // Text processing
  numericOnly?: boolean;
  uppercase?: boolean;
  lowercase?: boolean;
  
  // Advanced
  swapHiddenInput?: boolean;
  initValue?: string;
  document?: Document; // Custom document object (default: global document)
  onValueChanged?: (event: CleaveChangeEvent) => void;
}

interface CleaveChangeEvent {
  target: {
    name: string;
    value: string;
    rawValue: string;
  };
}

Vanilla JavaScript Usage

React Integration

React component wrapper providing controlled and uncontrolled component patterns with full prop-based configuration and event handling.

/**
 * Cleave React Component
 */
interface CleaveReactProps extends CleaveOptions {
  value?: string;
  onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
  onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
  onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
  onKeyDown?: (event: React.KeyboardEvent<HTMLInputElement>) => void;
  onInit?: (cleave: CleaveInstance) => void;
  htmlRef?: (ref: HTMLInputElement) => void;
  options?: CleaveOptions;
  [key: string]: any; // Additional HTML input props
}

interface CleaveInstance {
  setRawValue(value: string): void;
  getRawValue(): string;
  getFormattedValue(): string;
  getISOFormatDate(): string;
  getISOFormatTime(): string;
  setPhoneRegionCode(regionCode: string): void;
  destroy(): void; // Vanilla JS only
}

React Integration

Angular Integration

AngularJS directive providing two-way data binding with ngModel integration and configuration through directive attributes.

/**
 * Angular directive for Cleave.js integration
 * Usage: <input ng-model="value" cleave="getOptions()" on-init="onInit(instance)" />
 */
interface CleaveAngularDirective {
  // Directive attributes
  cleave: () => CleaveOptions; // Function returning options object
  onInit?: (instance: CleaveInstance) => void; // Initialization callback
  onValueChange?: (formattedValue: string) => void; // Value change callback
}

Angular Integration

Phone Number Formatting

International phone number formatting with support for 247 countries using Google's libphonenumber format patterns.

/**
 * Phone formatting requires country-specific addon files
 * Include before using: <script src="cleave-phone.{countryCode}.js"></script>
 */
interface PhoneFormattingOptions {
  phone: true;
  phoneRegionCode: string; // Two-letter country code (e.g., 'US', 'UK', 'AU')
}

// Available country codes (247 total)
type PhoneRegionCode = 'us' | 'uk' | 'au' | 'fr' | 'de' | 'jp' | 'cn' | 'in' | 'br' | 'ca' | /* ... 237 more */;

Phone Number Formatting

Types

/**
 * Credit card types detected by CreditCardDetector
 */
type CreditCardType = 'amex' | 'visa' | 'mastercard' | 'discover' | 'jcb' | 'dankort' | 'instapayment' | 'uatp' | 'mir' | 'unionPay' | 'general';

/**
 * Numeral thousand grouping styles
 */
type NumeralGroupStyle = 'thousand' | 'lakh' | 'wan' | 'none';

/**
 * Time format options
 */
type TimeFormat = '12' | '24';

/**
 * Date pattern tokens
 */
type DatePatternToken = 'd' | 'm' | 'Y';

/**
 * Time pattern tokens  
 */
type TimePatternToken = 'h' | 'm' | 's';