Cleave.js

Библиотека Cleave.js предназначена для форматирования пользовательского ввода в реальном времени без изменения исходного значения данных. Основная идея заключается в разделении отображаемого значения и фактического значения, которое может быть использовано в логике приложения или отправлено на сервер.

Ключевой принцип работы заключается в обработке input-событий и применении правил форматирования к строке, вводимой пользователем. При этом библиотека не выполняет валидацию в строгом смысле, а концентрируется именно на визуальном представлении данных.

Основные сценарии применения включают:

форматирование номеров банковских карт;
приведение телефонных номеров к заданному региональному формату;
отображение чисел с разделителями тысяч;
форматирование дат;
кастомные маски с произвольными разделителями и блоками.

Установка и подключение

Библиотека распространяется через npm и может быть подключена как модуль ES или CommonJS.

Установка через npm

npm install cleave.js

Подключение как модуль

import Cleave from 'cleave.js';

Подключение через CDN

<script src="https://cdn.jsdelivr.net/npm/cleave.js/dist/cleave.min.js"></script>

При подключении через CDN глобальный объект Cleave становится доступным в области window.

Базовая модель работы

Cleave.js работает как обёртка над DOM-элементом input. При инициализации создаётся экземпляр, который подписывается на события ввода и изменения значения поля.

const cleave = new Cleave('.input-element', {
    creditCard: true
});

В этом случае ввод автоматически форматируется как номер банковской карты с группировкой по 4 цифры.

Внутренне библиотека:

перехватывает вводимые символы;
удаляет неподходящие символы;
применяет форматирование;
обновляет значение поля.

Форматирование банковских карт

Один из наиболее распространённых режимов — creditCard.

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

Поддерживаются основные типы карт:

Visa
MasterCard
American Express
Discover

Алгоритм определения типа карты основан на префиксах (BIN range). Форматирование автоматически подстраивается под длину номера и структуру.

Дополнительный режим визуального разделения может быть расширен кастомными блоками:

new Cleave('.card-input', {
    creditCard: true,
    onCreditCardTypeChanged: function (type) {
        console.log(type);
    }
});

Телефонные номера и региональные форматы

Cleave.js содержит встроенные пресеты для телефонов различных стран.

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

Возможности включают:

автоматическое добавление кода страны;
форматирование по национальным правилам;
адаптацию длины номера;
удаление лишних символов.

Для разных регионов применяются различные маски, например:

США: (123) 456-7890
Великобритания: +44 20 1234 5678
Россия: +7 (999) 123-45-67

Числовой формат (numeral)

Режим numeral используется для форматирования чисел с разделителями, десятичными знаками и ограничениями.

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

Поддерживаемые группы:

thousand — стандартная группировка по 3 цифры;
lakh — индийская система;
wan — китайская система.

Дополнительные параметры:

new Cleave('.number-input', {
    numeral: true,
    numeralDecimalMark: '.',
    delimiter: ',',
    numeralDecimalScale: 2
});

Особенности режима:

автоматическое удаление нечисловых символов;
контроль количества знаков после запятой;
поддержка отрицательных чисел.

Форматирование дат

Режим date используется для приведения ввода к структурированному виду.

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

Возможные варианты паттернов:

d — день;
m — месяц;
Y — год.

Примеры комбинаций:

['d', 'm', 'Y']   // 31/12/2025
['Y', 'm', 'd']   // 2025-12-31

Также поддерживается ограничение диапазонов значений:

корректировка месяца от 1 до 12;
контроль количества дней в месяце;
нормализация года.

Кастомные маски и блоки

Наиболее гибкий механизм Cleave.js основан на использовании blocks, delimiter и numericOnly.

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

Результат:

123-456-7890

Механизм блоков позволяет описывать любую структуру ввода:

серийные номера;
идентификаторы;
коды подтверждения;
внутренние форматы систем.

Пример сложной структуры:

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

Delimiter и управление символами

Параметр delimiter определяет символ разделения блоков.

delimiter: '-'
delimiter: ' '
delimiter: '/'

Дополнительно поддерживаются массивы разделителей:

delimiter: ['(', ')', ' ']

Такой подход используется для сложных телефонных или идентификационных форматов.

Поведение при вводе и очистке

Cleave.js использует стратегию переформатирования строки при каждом изменении.

Основные этапы:

Получение текущего значения поля;
Очистка от неподходящих символов;
Применение маски;
Обновление DOM-значения.

Особенность заключается в том, что позиция курсора корректируется автоматически, что предотвращает “прыжки” каретки при вводе.

Управление экземпляром

После инициализации доступен объект экземпляра, содержащий методы управления состоянием.

const cleave = new Cleave('.input', {
    numeral: true
});

Основные операции:

cleave.setRawValue('1234567');
cleave.getRawValue();
cleave.destroy();

setRawValue — установка необработанного значения;
getRawValue — получение “чистого” значения без форматирования;
destroy — отключение обработки и возврат к обычному input.

Обработка событий

Cleave.js предоставляет события изменения состояния.

new Cleave('.input', {
    onValueChanged: function (e) {
        console.log(e.target.value);
        console.log(e.target.rawValue);
    }
});

Структура события включает:

отформатированное значение;
необработанное значение;
тип изменения.

Это позволяет синхронизировать данные с внешними моделями состояния.

Интеграция с фреймворками

React

Существует обёртка для React:

import Cleave from 'cleave.js/react';

<Cleave
    options={{ numeral: true }}
    onCha nge={handleChange}
/>

Компонент управляет жизненным циклом экземпляра и синхронизацией props.

Vue

Интеграция возможна через директивы или прямую инициализацию в mounted-хуке.

mounted() {
    this.cleave = new Cleave(this.$refs.input, {
        date: true
    });
}

Angular

Используется инициализация в lifecycle-хуках компонентов:

ngAfterViewInit() {
    new Cleave(this.input.nativeElement, {
        phone: true
    });
}

Ограничения и особенности поведения

Поведение библиотеки имеет ряд характерных ограничений:

отсутствие полноценной валидации;
зависимость от корректного DOM input;
сложность кастомизации нестандартных сценариев ввода;
необходимость ручного управления в некоторых SPA-сценариях.

При этом обеспечивается высокая стабильность форматирования и предсказуемость результата.

Внутренний механизм форматирования

Архитектура Cleave.js базируется на последовательной обработке строки:

normalization layer — удаление лишних символов;
pattern engine — применение правил маски;
formatting layer — вставка разделителей;
cursor engine — коррекция позиции ввода.

Такое разделение обеспечивает независимость логики форматирования от UI-слоя и упрощает расширение поведения.

Кастомные пресеты и расширение логики

Расширение функциональности реализуется через создание собственных форматов.

Пример пользовательского сценария:

new Cleave('.input', {
    prefix: 'ID-',
    blocks: [3, 3, 3],
    delimiter: '-'
});

Также возможна комбинация числовых и текстовых ограничений через кастомные обработчики событий.

Производительность и оптимизация

Cleave.js оптимизирована для работы с частыми input-событиями:

минимизация операций над DOM;
отсутствие тяжёлых регулярных выражений в горячем цикле;
переиспользование внутренних структур состояния.

При этом производительность может зависеть от сложности маски и количества одновременно активных полей.

Поведение при вставке данных

При вставке (paste) применяется полная переработка строки:

удаление форматирования;
извлечение валидных символов;
повторное применение маски.

Это позволяет корректно обрабатывать внешние источники данных без нарушения структуры поля.