Cleave.js — JavaScript-библиотека, предназначенная для автоматического форматирования пользовательского ввода в текстовых полях. Основная идея заключается в том, чтобы отделить «сырые» данные, вводимые пользователем, от визуально структурированного представления, которое повышает читаемость и снижает вероятность ошибок при вводе. Библиотека работает на уровне DOM-элементов и не требует сложной интеграции с фреймворками, хотя может использоваться совместно с React, Vue, Angular и другими современными инструментами.
Ключевая задача Cleave.js заключается в динамическом преобразовании строк, вводимых в input-поля, в заранее определённый формат. При этом исходное значение остаётся логически неизменным, а отображаемое — адаптируется в реальном времени.
Типичные примеры таких преобразований:
1234567812345678 →
1234 5678 1234 567879001234567 →
+7 900 123 45 6701012026 → 01/01/2026Подобное разделение улучшает UX и снижает когнитивную нагрузку при вводе длинных числовых или структурированных значений.
В основе библиотеки лежит обработка событий ввода
(input, keydown, paste) с
последующим преобразованием значения поля. Внутри реализован
механизм:
Особое внимание уделяется работе с кареткой (cursor position). При изменении строки библиотека пересчитывает позицию курсора так, чтобы пользовательский ввод оставался естественным и не «прыгал» при форматировании.
Cleave.js поддерживает работу с числовыми последовательностями, включая разделение по группам разрядов:
1000000 → 1 000 000Встроенная логика позволяет учитывать локаль и привычные форматы отображения чисел.
Библиотека предоставляет механизм для форматирования дат с настраиваемыми шаблонами:
DD/MM/YYYYMM-YYYYYYYY.MM.DDПри этом учитывается порядок ввода и автоматическое добавление разделителей.
Одна из наиболее распространённых функций — поддержка международных и локальных телефонных форматов. Cleave.js позволяет:
Пример логики:
+7 (___) ___ __ __Библиотека автоматически распознаёт тип карты по первым цифрам (BIN/IIN) и применяет соответствующее форматирование:
Также возможно включение разделения по 4 цифры и валидация длины номера.
Подключение Cleave.js обычно выполняется через создание экземпляра класса Cleave, который привязывается к DOM-элементу:
const cleave = new Cleave('.input-card', {
creditCard: true
});Или более универсальный вариант:
const cleave = new Cleave('.input-phone', {
phone: true,
phoneRegionCode: 'RU'
});Конфигурация задаётся через объект параметров, который определяет поведение форматирования.
numeral — включение числового режимаdate — активация работы с датамиphone — режим телефонного номераcreditCard — режим банковской картыdelimiter — символ разделителяprefix — фиксированный префикс (например,
валютный)noImmediatePrefix — управление отображением
префиксаrawValueTrimPrefix — удаление префикса при получении
«сырого» значенияuppercase / lowercase — преобразование
регистраCleave.js позволяет задавать сложные маски через blocks
и delimiter:
new Cleave('.input-custom', {
blocks: [3, 3, 4],
delimiter: '-'
});Результат:
123-456-7890При инициализации библиотека создаёт внутреннюю модель состояния input-поля. В процессе работы отслеживаются:
Каждое изменение проходит через пайплайн:
Особенность заключается в том, что Cleave.js не блокирует стандартное поведение input, а накладывает поверх него слой обработки.
Одним из ключевых аспектов является разделение отображаемого значения и исходного значения.
1 000 0001000000Для получения исходного значения используется метод:
cleave.getRawValue();Это особенно важно при отправке данных на сервер, где форматирование не должно присутствовать.
Cleave.js позволяет создавать собственные маски без привязки к готовым типам. Используются механизмы:
blocks — сегментация строкиnumericOnly — ограничение на числаdelimiters — массив или строка разделителейПример сложной маски:
new Cleave('.input-code', {
blocks: [4, 4, 4, 4],
delimiter: ' '
});Также возможно комбинирование с регулярными выражениями для предобработки данных.
При вставке текста Cleave.js:
Это позволяет корректно обрабатывать данные из внешних источников, включая банковские формы и CRM-системы.
Библиотека изначально написана на чистом JavaScript и не имеет жёсткой зависимости от фреймворков. Однако часто используется в связке с:
Интеграция обычно заключается в привязке экземпляра Cleave к lifecycle-методам компонента.
Cleave.js не требует виртуального DOM и работает напрямую с input-элементами. Однако при динамическом удалении или замене элементов необходимо уничтожать экземпляр:
cleave.destroy();Это предотвращает утечки памяти и некорректные обработчики событий.
Несмотря на универсальность, библиотека имеет ряд ограничений:
Фокус остаётся строго на визуальном преобразовании строки ввода в реальном времени.
При вводе символов, не соответствующих маске:
Это обеспечивает устойчивость интерфейса даже при некорректных действиях пользователя.
Cleave.js строится на нескольких ключевых принципах:
Такая архитектура делает библиотеку применимой в широком спектре интерфейсов, где требуется контроль над вводом структурированных данных.