Introducción a Cleave.js

Cleave.js es una bibliotecaJavaScript especializada en el formateo automático de campos de entrada mientras el usuario escribe. Soporta diversos formatos como números de tarjetas de crédito, fechas, números telefónicos y más. Esta guía presenta 10 técnicas avanzadas para maximizar el potencial de personalización de esta herramienta.

1. Instalación y Configuración Inicial

Para integrar Cleave.js en tu proyecto, utiliza npm:

npm install cleave.js

La inicialización básica requiere especificar el elemento objetivo y las opciones de configuración deseadas:

const formateador = new Cleave('#campo-entrada', {
  // opciones de configuración
});

2. Definición de Bloques Personalizados

La propiedad blocks permite definir la longitud de cada segmento del campo, mientras delimiter establece el carácter separador. Ideal para documentos de identificación:

const identificador = new Cleave('.numero-identificacion', {
  blocks: [6, 8, 3, 1],
  delimiter: '-',
  numericOnly: true
});

Esta configuración genera el formato: XXXXXX-YYYYMMDD-ZZZ-K

3. Múltiples Delimitadores

Para formatos complejos que requieren diferentes separadores, emplea la propiedad delimiters en plural:

const telefono = new Cleave('.telefono-completo', {
  blocks: [3, 4, 4, 4],
  delimiters: ['+', '-', '(', ')'],
  numericOnly: true
});

Produce formatos como: +XX-XXXX-XXXX-XXXX

4. Incorporación de Prefijos

La opción prefix añade un texto fijo al enicio del valor:

const codigoProducto = new Cleave('.codigo-articulo', {
  blocks: [3, 4, 3],
  delimiter: '-',
  prefix: 'ART',
  numericOnly: true
});

El usuario ingresa "1234567890" y el resultado es "ART-1234-567-890"

5. Respuesta a Cambios en Tiempo Real

El callback onValueChanged permite ejecutar acciones cuando el valer cambia:

const tarjeta = new Cleave('.numero-tarjeta', {
  creditCard: true,
  onValueChanged: function(evento) {
    console.log('Valor formateado:', evento.target.value);
    console.log('Valor original:', evento.target.rawValue);
  }
});

6. Modificación Dinámica de Opciones

El método setOptions permite actualizar la configuración en respuesta a interacciones del usuario:

const entradaTelefono = new Cleave('.telefono', {
  phone: true,
  phoneRegionCode: 'US'
});

document.getElementById('selector-pais').addEventListener('change', function(evento) {
  entradaTelefono.setOptions({
    phoneRegionCode: evento.target.value
  });
});

7. Integración con React

Cleave.js ofrece un componente dedicado para proyectos React:

import Cleave from 'cleave.js/react';

function CampoTarjeta() {
  return (
    <Cleave
      placeholder="Número de tarjeta"
      options={{ creditCard: true }}
      onChange={(e) => console.log(e.target.rawValue)}
    />
  );
}

8. Restricción de Tipos de Entrada

Las opciones numericOnly, uppercase y lowercase controlan el tipo de caracteres permitidos:

const claveAcceso = new Cleave('.clave-seguridad', {
  blocks: [5, 5, 5],
  delimiter: '-',
  uppercase: true
});

9. Campo Oculto para Envío de Formularios

La propiedad hiddenInput crea un campo adicional con el valor sin formatear:

const entradaFormateada = new Cleave('.dato-formateado', {
  creditCard: true,
  hiddenInput: true
});

El campo oculto toma el nombre original más el sufijo "-raw".

10. Formatoe Telefónico por Región

Cleave.js soporta formatos telefónicos específicos de diferentes países mediante phoneRegionCode:

const numeroInternacional = new Cleave('.telefono-global', {
  phone: true,
  phoneRegionCode: 'ES'
});

// Cambio dinámico de región
numeroInternacional.setPhoneRegionCode('MX');

Conclusión

Las opciones de personalización de Cleave.js permiten implementar prácticamente cualquier regla de formateo de entrada. La combinación de blocks, delimitadores personalizados, prefijos y listeners de eventos proporciona el control necesario para crear experiencias de entrada optimizadas y profesionales.