Como Usar Máscara de Input para CPF e Melhorar a Experiência do Usuário

Uma máscara de input para CPF aplica automaticamente a formatação XXX.XXX.XXX-XX conforme o usuário digita, reduz erros de preenchimento em até 70% e elimina a necessidade de instrução explícita sobre o formato. Combinada com validação em tempo real e feedback visual, transforma o campo de CPF em um elemento fluido do formulário — em vez de um ponto de abandono.

Introdução

O campo de CPF é um dos mais preenchidos em formulários brasileiros, presente em cadastros, checkouts e sistemas governamentais. Apesar disso, muitos sites ainda apresentam campos sem máscara, sem validação em tempo real e sem feedback visual, resultando em erros de digitação, frustração e abandono de formulários. Uma máscara de input bem implementada transforma o preenchimento de CPF em uma experiência fluida e intuitiva.

Por que a máscara de CPF importa

O CPF possui 11 dígitos numéricos, que sem formatação visual tornam-se difíceis de verificar. A máscara no formato XXX.XXX.XXX-XX oferece benefícios diretos.

Redução de erros -- a máscara impede a entrada de caracteres inválidos, reduzindo erros de digitação em até 70%.

Feedback imediato -- o usuário sabe instantaneamente se o CPF está no formato correto.

Acessibilidade -- a segmentação visual ajuda usuários com dificuldades de leitura a conferir os números.

Implementação com JavaScript puro

A implementação mais leve e sem dependências utiliza JavaScript puro para aplicar a máscara.

function aplicarMascaraCPF(input) {
    input.addEventListener("input", function (e) {
    let valor = e.target.value.replace(/\D/g, "");

    if (valor.length > 11) {
    valor = valor.slice(0, 11);
    }

    if (valor.length > 9) {
    valor = valor.replace(
    /(\d{3})(\d{3})(\d{3})(\d{1,2})/,
    "$1.$2.$3-$4"
    );
    } else if (valor.length > 6) {
    valor = valor.replace(
    /(\d{3})(\d{3})(\d{1,3})/,
    "$1.$2.$3"
    );
    } else if (valor.length > 3) {
    valor = valor.replace(/(\d{3})(\d{1,3})/, "$1.$2");
    }

    e.target.value = valor;
    });

    // Tratar colagem de valores
    input.addEventListener("paste", function (e) {
    e.preventDefault();
    const textoColado = (e.clipboardData || window.clipboardData)
    .getData("text");
    const apenasNumeros = textoColado.replace(/\D/g, "").slice(0, 11);
    input.value = apenasNumeros;
    input.dispatchEvent(new Event("input"));
    });
}

// Uso
const campoCPF = document.getElementById("cpf");
aplicarMascaraCPF(campoCPF);

Validação em tempo real com feedback visual

Além da máscara, a validação em tempo real com feedback visual melhora significativamente a experiência.

<div class="campo-cpf">
    <label for="cpf">CPF</label>
    <input
    type="text"
    id="cpf"
    inputmode="numeric"
    maxlength="14"
    placeholder="000.000.000-00"
    autocomplete="off"
    aria-describedby="cpf-feedback"
    />
    <span id="cpf-feedback" class="feedback" role="alert"></span>
</div>

<style>
    .campo-cpf input.valido {
    border-color: #22c55e;
    background-color: #f0fdf4;
    }
    .campo-cpf input.invalido {
    border-color: #ef4444;
    background-color: #fef2f2;
    }
    .feedback {
    font-size: 0.875rem;
    margin-top: 0.25rem;
    display: block;
    }
    .feedback.erro { color: #ef4444; }
    .feedback.sucesso { color: #22c55e; }
</style>

function validarCPFComFeedback(input, feedbackEl) {
    input.addEventListener("input", function () {
    const cpfLimpo = input.value.replace(/\D/g, "");

    if (cpfLimpo.length < 11) {
    input.classList.remove("valido", "invalido");
    feedbackEl.textContent = "";
    return;
    }

    if (validarDigitosCPF(cpfLimpo)) {
    input.classList.add("valido");
    input.classList.remove("invalido");
    feedbackEl.textContent = "CPF válido";
    feedbackEl.className = "feedback sucesso";
    } else {
    input.classList.add("invalido");
    input.classList.remove("valido");
    feedbackEl.textContent = "CPF inválido. Verifique os números.";
    feedbackEl.className = "feedback erro";
    }
    });
}

Boas práticas de acessibilidade

A acessibilidade é fundamental para que todos os usuários possam preencher o campo de CPF sem dificuldades.

Atributo inputmode="numeric" -- exibe o teclado numérico em dispositivos móveis sem restringir o tipo do input a number.

Label visível e associado -- usar <label for="cpf"> garante que leitores de tela anunciem corretamente o campo.

Atributo aria-describedby -- associar o campo ao elemento de feedback para que leitores de tela anunciem validações.

Atributo role="alert" -- no elemento de feedback, faz com que mudanças sejam anunciadas automaticamente.

Placeholder como guia -- usar 000.000.000-00 como placeholder para indicar o formato esperado.

Não depender apenas de cor -- adicionar texto descritivo além da mudança de cor para indicar o estado do campo.

Integração da máscara com consulta à API

Para campos que exigem não apenas validação algorítmica, mas também consulta de dados, a máscara pode ser integrada com a API.

async function cpfComMascaraEConsulta(input, feedbackEl) {
    aplicarMascaraCPF(input);

    let debounceTimer;

    input.addEventListener("input", function () {
    clearTimeout(debounceTimer);
    const cpfLimpo = input.value.replace(/\D/g, "");

    if (cpfLimpo.length === 11 && validarDigitosCPF(cpfLimpo)) {
    debounceTimer = setTimeout(async () => {
    feedbackEl.textContent = "Consultando...";
    feedbackEl.className = "feedback";

    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpfLimpo}`,
    { headers: { "x-api-key": "SUA_API_KEY" } }
    );
    const resultado = await response.json();

    if (resultado.success) {
    feedbackEl.textContent = `CPF válido - ${resultado.data.name}`;
    feedbackEl.className = "feedback sucesso";
    } else {
    feedbackEl.textContent = "CPF não localizado na base";
    feedbackEl.className = "feedback erro";
    }
    }, 500);
    }
    });
}

Perguntas frequentes

A máscara de CPF precisa de uma biblioteca externa ou pode ser feita com JavaScript puro?

JavaScript puro é suficiente na maioria dos casos. A implementação com addEventListener("input") e expressões regulares não adiciona dependências ao projeto e funciona em todos os navegadores modernos. Bibliotecas como IMask ou Cleave.js são úteis quando o projeto já as utiliza para outros campos, mas não são obrigatórias para um campo de CPF isolado.

Como lidar com CPFs colados pelo usuário que já vêm formatados?

O evento paste deve ser interceptado para limpar a formatação antes de aplicar a máscara novamente. O snippet neste artigo faz exatamente isso: captura o texto colado, remove todos os não-dígitos com .replace(/\D/g, "") e redispara o evento input para que a máscara seja aplicada corretamente.

Como garantir conformidade com a LGPD ao coletar CPF em formulários?

Colete o CPF apenas quando houver finalidade legítima declarada ao usuário (emissão de NF, antifraude, etc.), não armazene o número em logs de frontend e use HTTPS em todos os formulários. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade — colete apenas o que for de fato necessário para a finalidade informada.

A integração com a API CPFHub.io pode ser feita diretamente no frontend?

Não é recomendado. A chave de API nunca deve ficar exposta no frontend, pois qualquer usuário pode inspecionar o código-fonte. A abordagem correta é criar um endpoint de backend ou serverless function que recebe o CPF, chama a API do CPFHub.io com a chave segura e devolve apenas os dados necessários ao frontend.

Conclusão

Uma máscara de input para CPF bem implementada é um investimento pequeno com retorno significativo em usabilidade, acessibilidade e conversão. Ao combinar formatação automática, validação em tempo real e feedback visual claro, o formulário se torna mais intuitivo e menos propenso a erros. A integração com a API de CPF adiciona uma camada de verificação que pode preencher automaticamente dados e aumentar a confiança do usuário.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e adicione validação de CPF em tempo real aos seus formulários hoje mesmo.