Como mascarar CPF na interface (###.###.###-##) sem perder usabilidade

Mascarar o CPF na interface sem perder usabilidade exige combinar duas técnicas complementares: a máscara de formatação (###.###.###-##), que guia a digitação e reduz erros, e a máscara de ocultação (123.***.***-00), que protege o dado após a consulta sem revelar o número completo na tela.

Introdução

Mascarar o CPF na interface é uma prática essencial para proteger dados pessoais e cumprir requisitos da LGPD. No entanto, uma máscara mal implementada pode prejudicar a usabilidade: dificultar a digitação, confundir o usuário ou impedir a verificação visual do número. O desafio é aplicar o mascaramento de forma que proteja a informação sem criar fricção. Quando combinadas com a consulta via API da CPFHub.io, essas técnicas entregam segurança e uma experiência de digitação fluida em qualquer fluxo de cadastro.

Máscara de formatação vs. máscara de ocultação

Existem dois tipos de máscara para CPF, e é importante não confundi-los:

• Máscara de formatação — Aplica automaticamente os pontos e o hífen enquanto o usuário digita (ex: 123.456.789-00). O objetivo é facilitar a leitura e reduzir erros de digitação.

• Máscara de ocultação — Substitui parte dos dígitos por asteriscos ou outros caracteres para proteger o dado após a digitação (ex: 123.***.***-00). O objetivo é segurança e privacidade.

Ambas as máscaras são importantes, mas em momentos diferentes do fluxo.

Implementando a máscara de formatação

A máscara de formatação deve ser aplicada durante a digitação, sem interferir no ritmo do usuário.

Regras da máscara de formatação

• Aceitar apenas dígitos numéricos.
• Inserir ponto após o 3o e o 6o dígito.
• Inserir hífen após o 9o dígito.
• Limitar a 14 caracteres (11 dígitos + 2 pontos + 1 hífen).
• Permitir apagar caracteres sem que a máscara "trave".

Implementação em JavaScript puro

function aplicarMascaraCPF(valor) {
    // Remove tudo que não é dígito
    const numeros = valor.replace(/\D/g, '').slice(0, 11);

    // Aplica a máscara progressivamente
    if (numeros.length <= 3) return numeros;
    if (numeros.length <= 6) return `${numeros.slice(0, 3)}.${numeros.slice(3)}`;
    if (numeros.length <= 9)
    return `${numeros.slice(0, 3)}.${numeros.slice(3, 6)}.${numeros.slice(6)}`;
    return `${numeros.slice(0, 3)}.${numeros.slice(3, 6)}.${numeros.slice(6, 9)}-${numeros.slice(9)}`;
}

// Uso em um input
document.getElementById('cpf').addEventListener('input', function (e) {
    const posicaoCursor = e.target.selectionStart;
    const valorAnterior = e.target.value;
    e.target.value = aplicarMascaraCPF(e.target.value);

    // Ajustar posição do cursor após a máscara
    const diff = e.target.value.length - valorAnterior.length;
    e.target.setSelectionRange(posicaoCursor + diff, posicaoCursor + diff);
});

Armadilhas comuns na máscara de formatação

• Cursor saltando — Ao inserir pontos e hífens automaticamente, o cursor pode pular para o final do campo. A solução é calcular a posição correta após a máscara.

• Apagar ficando travado — Se a máscara reaplica os caracteres ao apagar, o usuário não consegue corrigir. Permita sempre a remoção de caracteres.

• Colar com formato — Se o usuário cola "123.456.789-00", a máscara deve limpar a formatação existente antes de reaplicar.

• Input numérico no mobile — Use inputMode="numeric" para que o teclado numérico apareça em dispositivos móveis, facilitando a digitação.

Implementando a máscara de ocultação

A máscara de ocultação é aplicada após a digitação, quando o CPF precisa ser exibido na interface sem revelar o número completo.

Padrões de ocultação por contexto

Funções de ocultação em Python

def mascarar_cpf_parcial(cpf):
    """Exibe início e final: 123.***.***-00"""
    limpo = cpf.replace(".", "").replace("-", "")
    return f"{limpo[:3]}.***.***-{limpo[9:]}"

def mascarar_cpf_minimo(cpf):
    """Exibe apenas os últimos 2 dígitos: ***.***.***-00"""
    limpo = cpf.replace(".", "").replace("-", "")
    return f"***.***.***-{limpo[9:]}"

def mascarar_cpf_central(cpf):
    """Exibe apenas o bloco central: ***.456.***-**"""
    limpo = cpf.replace(".", "").replace("-", "")
    return f"***.{limpo[3:6]}.***-**"

# Exemplo de uso com dados da API CPFHub.io
import requests

def consultar_e_mascarar(cpf_numero):
    url = f"https://api.cpfhub.io/cpf/{cpf_numero}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

    response = requests.get(url, headers=headers, timeout=10)
    data = response.json()

    if data.get("success"):
    cpf_original = data["data"]["cpf"]
    return {
    "cpf_mascarado": mascarar_cpf_parcial(cpf_original),
    "nome": data["data"]["name"],
    "genero": data["data"]["gender"]
    }
    return None

Máscara de exibição no front-end vs. backend

Uma decisão arquitetural importante é onde aplicar a máscara de ocultação:

Mascaramento no backend (recomendado)

O backend aplica a máscara antes de enviar os dados ao front-end. Assim, o CPF completo nunca trafega para o navegador do usuário.

• Vantagem — O CPF completo não fica exposto no DOM, no estado da aplicação ou em logs do front-end.

• Desvantagem — Se o front-end precisar do CPF completo em outro momento, uma nova requisição será necessária.

Mascaramento no front-end

O front-end recebe o CPF completo e aplica a máscara na renderização.

• Vantagem — Flexibilidade para alternar entre modos de exibição (mascarado/revelado) sem nova requisição.

• Desvantagem — O CPF completo fica acessível no DevTools do navegador.

Para a maioria dos casos, o mascaramento no backend é a abordagem mais segura.

Acessibilidade no mascaramento

O mascaramento deve funcionar corretamente com tecnologias assistivas:

• Leitores de tela — Asteriscos são lidos literalmente ("asterisco asterisco asterisco"). Use aria-label para fornecer uma descrição alternativa: aria-label="CPF terminado em 00".

• Contraste visual — Os asteriscos ou caracteres de máscara devem ter contraste suficiente com o fundo.

• Navegação por teclado — Se houver botão de revelar/ocultar, ele deve ser acessível via Tab e Enter.

Máscara durante a consulta via API

Um padrão útil é mascarar o CPF no campo após a consulta ser concluída com sucesso. Isso protege o dado na tela sem que o usuário precise agir:

1. O usuário digita o CPF: 123.456.789-00 (máscara de formatação ativa).
2. A aplicação consulta a API e recebe os dados.
3. O campo de CPF muda para: 123.***.***-00 (máscara de ocultação aplicada).
4. Um ícone de check confirma que a consulta foi bem-sucedida.

Essa transição automática comunica ao usuário que o CPF foi processado e agora está protegido na tela.

Testando a implementação das máscaras

Verifique os seguintes cenários em testes:

• Digitação completa — O CPF é formatado corretamente ao digitar todos os 11 dígitos.

• Apagar e redigitar — O usuário pode apagar dígitos e a máscara se ajusta corretamente.

• Colar CPF — Ao colar um CPF com ou sem formatação, a máscara é aplicada corretamente.

• Dispositivos móveis — O teclado numérico aparece e a máscara funciona sem saltos de cursor.

• Leitores de tela — Os valores mascarados são comunicados de forma compreensível.

Perguntas frequentes

A LGPD exige mascaramento de CPF na interface?

A Lei nº 13.709/2018 (LGPD) não especifica técnicas de mascaramento, mas exige medidas técnicas e administrativas para proteger dados pessoais contra acesso não autorizado. O mascaramento do CPF na interface é uma boa prática que demonstra conformidade com o princípio da segurança (Art. 46), especialmente em telas acessadas por múltiplos operadores, como painéis de atendimento.

Qual o padrão de ocultação mais adequado para telas de atendimento ao cliente?

Para telas acessadas por atendentes que não precisam ver o CPF completo, o padrão ***.456.***-** (bloco central visível) é o mais equilibrado: permite confirmar que o cliente informou o CPF correto sem expor os blocos mais sensíveis. Para telas de autoatendimento onde o próprio titular confirma os dados, exibir o CPF completo é aceitável.

Como garantir que a máscara de formatação não quebre ao colar CPF com formatação diferente?

Sempre limpe o valor antes de aplicar a máscara: remova pontos, hífens e espaços com .replace(/\D/g, ''). Assim, seja qual for o formato colado (com ou sem pontuação, com espaços), a máscara sempre parte dos dígitos brutos e reaplica o padrão correto. Teste com CPFs colados de PDFs, e-mails e planilhas, que costumam ter formatos inconsistentes.

O campo de CPF deve usar type="text" ou type="number" no HTML?

Sempre type="text". O type="number" remove zeros à esquerda, o que quebraria CPFs que começam com 0. Use inputMode="numeric" combinado com type="text" para exibir o teclado numérico em dispositivos móveis sem perder os zeros. Adicione também autocomplete="off" para evitar que o navegador sugira CPFs de outros usuários em campos compartilhados.

Conclusão

Mascarar CPF na interface exige atenção a dois aspectos distintos: a máscara de formatação (que facilita a digitação) e a máscara de ocultação (que protege o dado). Implementar ambas corretamente, respeitando a posição do cursor, a acessibilidade e a segurança dos dados, resulta em uma experiência fluida e em conformidade com a LGPD.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e combine o mascaramento de interface com a validação via API para garantir dados corretos e protegidos em todos os seus fluxos de cadastro.