Интеграция в проекты на чистом JavaScript

Cleave.js представляет собой лёгкую библиотеку для форматирования пользовательского ввода в реальном времени. В контексте чистого JavaScript она чаще всего подключается напрямую в браузере без сборщиков и бандлеров, что делает CDN-интеграцию базовым способом использования.

Подключение через CDN осуществляется добавлением <script> перед закрывающим тегом </body>:

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

После загрузки скрипта глобально становится доступен конструктор Cleave.

Инициализация выполняется после загрузки DOM:

<input id="phone" type="text" />

<script>
  new Cleave('#phone', {
    phone: true,
    phoneRegionCode: 'RU'
  });
</script>

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

Базовая инициализация в чистом JavaScript

Основная модель использования строится вокруг создания экземпляра:

const cleaveInstance = new Cleave(selector, options);

Где selector может быть:

  • CSS-селектор строки ('#input')
  • DOM-элемент (document.querySelector('#input'))

Пример прямой работы с элементом:

const input = document.querySelector('#credit-card');

const creditCardFormatter = new Cleave(input, {
  creditCard: true
});

Библиотека автоматически:

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

Форматирование чисел и базовых значений

Одним из наиболее частых сценариев является работа с числовыми значениями.

new Cleave('#amount', {
  numeral: true,
  numeralThousandsGroupStyle: 'thousand'
});

Поведение:

  • автоматическое добавление разделителей тысяч
  • нормализация ввода
  • фильтрация недопустимых символов

Дополнительные параметры числового режима:

new Cleave('#price', {
  numeral: true,
  numeralDecimalMark: '.',
  delimiter: ',',
  numeralDecimalScale: 2
});

Особенность интеграции в чистом JS — отсутствие необходимости преобразования строки вручную: библиотека поддерживает синхронизацию значения DOM-элемента в реальном времени.

Работа с телефонными номерами

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

new Cleave('#phone', {
  phone: true,
  phoneRegionCode: 'US'
});

При этом библиотека:

  • определяет структуру номера по региону
  • добавляет пробелы и разделители
  • корректирует ввод при вставке

Для универсальных форматов:

new Cleave('#phone', {
  delimiters: ['(', ')', ' ', '-'],
  blocks: [0, 3, 0, 3, 4],
  numericOnly: true
});

Такой подход полезен при кастомных форматах, где требуется полный контроль над структурой.

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

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

new Cleave('#card', {
  creditCard: true
});

Поддерживаемые особенности:

  • автоопределение типа карты
  • группировка по 4 цифры
  • очистка пробелов при вставке

При необходимости можно комбинировать с событиями DOM:

const card = new Cleave('#card', { creditCard: true });

document.querySelector('#card').addEventListener('change', () => {
  console.log(card.getRawValue());
});

Использование кастомных блоков форматирования

Гибкость Cleave.js проявляется в возможности задания структуры через blocks и delimiters.

new Cleave('#serial', {
  blocks: [4, 4, 4, 4],
  delimiter: '-',
  numericOnly: true
});

Результат:

1234-5678-9012-3456

Расширенные сценарии:

new Cleave('#custom', {
  blocks: [3, 3, 4],
  delimiters: ['.', '.', '-'],
  numericOnly: true
});

Такая модель используется для:

  • серийных номеров
  • артикулов
  • внутренних идентификаторов

Управление экземпляром и доступ к данным

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

Получение «сырого» значения

const raw = cleaveInstance.getRawValue();

Используется для:

  • отправки данных на сервер
  • валидации без форматирования

Программная установка значения

cleaveInstance.setRawValue('1234567890');

Форматирование применяется автоматически после установки.

Динамическое обновление конфигурации

В чистом JavaScript часто возникает необходимость менять формат «на лету».

cleaveInstance.setPhoneRegionCode('GB');

или полная переинициализация:

cleaveInstance.destroy();

new Cleave('#phone', {
  phone: true,
  phoneRegionCode: 'DE'
});

Такой подход используется при:

  • переключении страны пользователя
  • смене режима ввода
  • динамических формах

Интеграция с нативными событиями DOM

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

const input = document.querySelector('#amount');

input.addEventListener('input', () => {
  console.log(input.value);
});

Особенность заключается в том, что значение уже отформатировано в момент события.

Для отслеживания «чистого» значения:

input.addEventListener('blur', () => {
  console.log(cleaveInstance.getRawValue());
});

Работа с вставкой данных (paste)

При вставке больших строк библиотека автоматически:

  • очищает недопустимые символы
  • перераспределяет блоки
  • применяет форматирование целиком
new Cleave('#input', {
  blocks: [4, 4, 4],
  delimiter: ' '
});

Если вставить:

123456781234

результат будет:

1234 5678 1234

Подключение нескольких инстансов на странице

Чистый JavaScript позволяет без ограничений инициализировать множество полей:

document.querySelectorAll('.date-input').forEach((el) => {
  new Cleave(el, {
    date: true,
    datePattern: ['d', 'm', 'Y']
  });
});

Такой подход используется в формах с повторяющимися блоками:

  • адреса
  • платежные данные
  • анкеты

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

Поддержка дат позволяет стандартизировать ввод.

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

Поведение:

  • автоматическая вставка разделителей
  • контроль диапазонов
  • нормализация ввода

Расширенные варианты:

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

Очистка и уничтожение экземпляра

При работе в SPA или динамических интерфейсах важно освобождать ресурсы.

cleaveInstance.destroy();

После вызова:

  • обработчики событий удаляются
  • форматирование прекращается
  • DOM возвращается к обычному состоянию

Это критично при:

  • удалении компонентов
  • перерисовке интерфейса
  • переключении страниц без перезагрузки

Обработка ошибок и нестандартного ввода

Cleave.js не является валидатором, но влияет на ввод.

Типичные сценарии:

  • вставка символов вне маски игнорируется
  • переполнение блоков обрезается
  • неверные символы удаляются автоматически

Пример числового режима:

new Cleave('#num', {
  numeral: true
});

Любые буквы будут отфильтрованы на уровне ввода.

Особенности работы в чистом JavaScript окружении

При использовании без фреймворков важно учитывать:

  • инициализация должна происходить после загрузки DOM
  • повторная инициализация без destroy() приводит к дублированию обработчиков
  • прямое изменение value через JS может требовать повторного форматирования

Корректный порядок:

document.addEventListener('DOMContentLoaded', () => {
  new Cleave('#input', { numeral: true });
});

Комбинирование нескольких режимов

Некоторые сценарии требуют объединения логики:

new Cleave('#complex', {
  numeral: true,
  numeralThousandsGroupStyle: 'thousand',
  prefix: '$',
  noImmediatePrefix: true
});

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

  • визуальный префикс
  • строгая числовая структура
  • контроль формата ввода

Работа с множественными форматами в одном поле

Иногда формат зависит от длины или контекста:

const input = document.querySelector('#dynamic');

const cleave = new Cleave(input, {
  numericOnly: true,
  blocks: [3, 3, 4]
});

input.addEventListener('focus', () => {
  cleave.setRawValue(input.value.replace(/\D/g, ''));
});

Такой подход применяется при:

  • адаптивных формах
  • миграции старых данных
  • смешанных форматах ввода
Оглавление