# Como usar tooltips e mensagens de ajuda contextuais em campos de CPF

> Aprenda a implementar tooltips e mensagens de ajuda contextuais em campos de CPF para melhorar a experiência do usuário e reduzir erros.

**Publicado:** 10/08/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-usar-tooltips-e-mensagens-de-ajuda-contextuais-em-campos-de-cpf

---


Tooltips e mensagens de ajuda contextuais em campos de CPF reduzem erros de preenchimento, diminuem o abandono de formulários e aumentam a confiança do usuário — especialmente quando combinados com validação em tempo real via API. A abordagem consiste em exibir orientações no momento certo: um tooltip explicando por que o CPF é solicitado, um inline hint com o formato esperado, e feedback progressivo conforme o usuário digita, culminando na exibição do nome do titular quando a validação é bem-sucedida.

## Introdução

O campo de CPF é um dos elementos mais críticos em formulários brasileiros. Além de ser um dado sensível que gera hesitação em muitos usuários, o CPF também é fonte frequente de erros de digitação, formatação incorreta e dúvidas sobre por que a empresa precisa dessa informação. Cada uma dessas barreiras contribui para o abandono do formulário.

**Tooltips e mensagens de ajuda contextuais** são ferramentas de UX que podem reduzir significativamente esses problemas, fornecendo orientação precisa no momento exato em que o usuário precisa. Combinadas com a **validação de CPF via API**, essas técnicas criam uma experiência fluida que transmite confiança e reduz erros.

## Tipos de mensagens contextuais

Existem diferentes abordagens para fornecer ajuda contextual em campos de formulário:

* **Tooltips (hover/focus)** -- Pequenas caixas de texto que aparecem ao passar o mouse ou focar no campo. Ideais para informações breves.

* **Inline hints** -- Textos exibidos abaixo ou ao lado do campo, visíveis permanentemente. Úteis para instruções de formatação.

* **Mensagens de validação em tempo real** -- Feedback dinâmico que aparece conforme o usuário digita, indicando se o CPF é válido ou não.

* **Mensagens de erro** -- Exibidas apenas quando o usuário comete um erro, com orientação clara sobre como corrigi-lo.

* **Mensagens de sucesso** -- Confirmação visual de que o CPF foi validado com sucesso, idealmente exibindo o nome do titular.

---

## Implementando tooltips informativos

### Por que pedimos seu CPF

O tooltip mais importante é aquele que explica **por que** a empresa precisa do CPF. Isso reduz a desconfiança do usuário:

```html
<div class="campo-cpf">
 <label for="cpf">
 CPF
 <span class="tooltip-trigger" aria-label="Por que pedimos seu CPF?">
 <svg width="16" height="16" viewBox="0 0 16 16">
 <circle cx="8" cy="8" r="7" stroke="#666" fill="none"/>
 <text x="8" y="12" text-anchor="middle" font-size="11" fill="#666">?</text>
 </svg>
 <span class="tooltip-content" role="tooltip">
 Precisamos do seu CPF para validar sua identidade e
 garantir a seguranca da sua conta. Seus dados sao
 protegidos conforme a LGPD.
 </span>
 </span>
 </label>
 <input type="text" id="cpf" name="cpf" placeholder="000.000.000-00"
 inputmode="numeric" maxlength="14" autocomplete="off" />
 <span class="campo-hint">Digite os 11 digitos do seu CPF.</span>
</div>
```

```css
.tooltip-trigger {
 position: relative;
 cursor: help;
 display: inline-block;
 margin-left: 4px;
}

.tooltip-content {
 display: none;
 position: absolute;
 bottom: 100%;
 left: 50%;
 transform: translateX(-50%);
 background: #333;
 color: #fff;
 padding: 8px 12px;
 border-radius: 4px;
 font-size: 13px;
 line-height: 1.4;
 width: 250px;
 text-align: center;
 z-index: 100;
}

.tooltip-trigger:hover .tooltip-content,
.tooltip-trigger:focus .tooltip-content {
 display: block;
}

.campo-hint {
 display: block;
 font-size: 12px;
 color: #888;
 margin-top: 4px;
}
```

---

## Mensagens de validação em tempo real

Combine tooltips com validação em tempo real via API para fornecer feedback progressivo:

```javascript
const cpfInput = document.getElementById('cpf');
const statusEl = document.getElementById('cpf-status');
let debounceTimer;

cpfInput.addEventListener('input', function(e) {
 const valor = e.target.value;
 const cpfLimpo = valor.replace(/\D/g, '');

 // Aplicar mascara
 e.target.value = formatarCpf(cpfLimpo);

 // Limpar status anterior
 statusEl.textContent = '';
 statusEl.className = 'campo-status';

 clearTimeout(debounceTimer);

 if (cpfLimpo.length < 11) {
 if (cpfLimpo.length > 0) {
 statusEl.textContent = `${cpfLimpo.length}/11 digitos informados.`;
 statusEl.className = 'campo-status info';
 }
 return;
 }

 if (cpfLimpo.length === 11) {
 // Validação sintatica local
 if (!validarDigitosCpf(cpfLimpo)) {
 statusEl.textContent = 'CPF invalido. Verifique os digitos informados.';
 statusEl.className = 'campo-status erro';
 return;
 }

 statusEl.textContent = 'Validando CPF...';
 statusEl.className = 'campo-status info';

 // Debounce para evitar chamadas excessivas
 debounceTimer = setTimeout(() => validarCpfApi(cpfLimpo), 500);
 }
});

async function validarCpfApi(cpf) {
 const controller = new AbortController();
 const timeoutId = setTimeout(() => controller.abort(), 30000);

 try {
 const response = await fetch(`/api/cpf/${cpf}`, {
 signal: controller.signal,
 });

 clearTimeout(timeoutId);

 const data = await response.json();

 if (data.success) {
 statusEl.innerHTML = `CPF validado. Titular: <strong>${data.data.name}</strong>`;
 statusEl.className = 'campo-status sucesso';
 } else {
 statusEl.textContent = 'CPF nao encontrado. Verifique o numero informado.';
 statusEl.className = 'campo-status erro';
 }
 } catch (error) {
 statusEl.textContent = 'Erro na validacao. Tente novamente.';
 statusEl.className = 'campo-status erro';
 }
}

function formatarCpf(cpf) {
 return cpf
 .replace(/(\d{3})(\d)/, '$1.$2')
 .replace(/(\d{3})(\d)/, '$1.$2')
 .replace(/(\d{3})(\d{1,2})$/, '$1-$2');
}

function validarDigitosCpf(cpf) {
 if (/^(\d)\1{10}$/.test(cpf)) return false;
 let soma = 0;
 for (let i = 0; i < 9; i++) soma += parseInt(cpf.charAt(i)) * (10 - i);
 let resto = 11 - (soma % 11);
 if (resto === 10 || resto === 11) resto = 0;
 if (resto !== parseInt(cpf.charAt(9))) return false;
 soma = 0;
 for (let i = 0; i < 10; i++) soma += parseInt(cpf.charAt(i)) * (11 - i);
 resto = 11 - (soma % 11);
 if (resto === 10 || resto === 11) resto = 0;
 return resto === parseInt(cpf.charAt(10));
}
```

---

## Mensagens de erro claras e acionáveis

Cada tipo de erro deve ter uma mensagem específica e útil:

| Situação | Mensagem ruim | Mensagem boa |
| --- | --- | --- |
| CPF incompleto | "Campo inválido" | "Faltam X dígitos para completar o CPF." |
| Dígitos verificadores errados | "Erro" | "Os dígitos do CPF não conferem. Verifique o número." |
| CPF não encontrado na base | "Inválido" | "CPF não encontrado. Confira se digitou corretamente." |
| Todos os dígitos iguais | "Inválido" | "CPF inválido. Não é permitido usar todos os dígitos iguais." |

---

## Exemplo de resposta da API para feedback visual

A API da [**CPFHub.io**](https://www.cpfhub.io/) retorna os dados do titular em um único objeto JSON, que pode ser usado diretamente para compor mensagens de sucesso personalizadas:

```json
{
 "success": true,
 "data": {
 "cpf": "12345678900",
 "name": "Joao da Silva",
 "nameUpper": "JOAO DA SILVA",
 "gender": "M",
 "birthDate": "15/06/1990",
 "day": 15,
 "month": 6,
 "year": 1990
 }
}
```

Com esses dados, a mensagem de sucesso pode incluir o nome do titular, aumentando a confiança do usuário de que está no lugar certo e que seus dados são tratados com seriedade.

---

## Estilos para os diferentes estados

```css
.campo-status {
 display: block;
 font-size: 13px;
 margin-top: 6px;
 padding: 4px 0;
 transition: color 0.2s ease;
}

.campo-status.info {
 color: #666;
}

.campo-status.sucesso {
 color: #2e7d32;
}

.campo-status.erro {
 color: #c62828;
}

/* Indicador visual no campo */
input.cpf-valido {
 border-color: #2e7d32;
 background-image: url('data:image/svg+xml,...'); /* Icone de check */
 background-repeat: no-repeat;
 background-position: right 12px center;
}

input.cpf-invalido {
 border-color: #c62828;
}
```

---

## Acessibilidade

Tooltips e mensagens contextuais devem ser acessíveis para todos os usuários. As diretrizes [WCAG 2.1](https://www.w3.org/TR/WCAG21/) estabelecem os requisitos mínimos de acessibilidade para componentes interativos em formulários:

* **Use aria-describedby** -- Associe mensagens de ajuda ao campo de input para que leitores de tela as anunciem.

* **Tooltips devem funcionar com teclado** -- Além do hover, tooltips devem abrir com focus (Tab).

* **Mensagens de erro no aria-live** -- Use `aria-live="polite"` na região de mensagens de status para que mudanças sejam anunciadas automaticamente.

* **Contraste de cores** -- Mensagens de erro, sucesso e informação devem ter contraste mínimo de 4.5:1 conforme WCAG 2.1.

```html
<input type="text" id="cpf" aria-describedby="cpf-hint cpf-status" />
<span id="cpf-hint" class="campo-hint">Digite os 11 digitos do seu CPF.</span>
<span id="cpf-status" class="campo-status" aria-live="polite"></span>
```

---

## Boas práticas

* **Não bloqueie o formulário durante a validação** -- Permita que o usuário continue preenchendo outros campos enquanto o CPF é validado.

* **Use debounce** -- Aguarde pelo menos 500ms após o último caractere digitado antes de chamar a API, evitando requisições desnecessárias.

* **Forneça alternativa offline** -- Se a validação via API falhar, permita que o usuário prossiga com validação apenas sintática.

* **Gerencie o volume de consultas** -- O plano gratuito da CPFHub.io oferece 50 consultas mensais; o debounce e a validação sintática local ajudam a concentrar as chamadas à API apenas em CPFs com dígitos verificadores válidos.

---

## Perguntas frequentes

### Qual é a diferença entre validação sintática de CPF e validação via API?
A validação sintática verifica apenas se os 11 dígitos e os dígitos verificadores matemáticos estão corretos — pode ser feita localmente, sem chamada de rede. A validação via API vai além: confirma se aquele CPF existe na base de dados e retorna o nome e data de nascimento do titular. Para campos de CPF em formulários críticos, o ideal é fazer as duas: validação sintática em tempo real (sem custo) e chamada à API para confirmar a identidade.

### Como evitar que a validação via API deixe o formulário lento?
Use debounce de 500ms no evento `input` para só disparar a chamada à API quando o usuário parar de digitar. Enquanto a API responde (latência de aproximadamente 900ms), exiba uma mensagem "Validando CPF..." para que o usuário saiba que algo está acontecendo. Se a chamada demorar mais que o esperado, permita que o usuário prossiga com validação apenas sintática.

### Tooltips são acessíveis para usuários de leitores de tela?
Sim, desde que implementados corretamente. Use `role="tooltip"` no elemento de conteúdo do tooltip, `aria-describedby` no input para associar o tooltip ao campo, e garanta que o tooltip seja acionável via teclado (focus), não apenas via hover. As diretrizes WCAG 2.1 exigem que componentes interativos sejam operáveis sem mouse.

### O que exibir quando a API retorna que o CPF não foi encontrado?
Exiba uma mensagem clara e acionável como "CPF não encontrado. Confira se digitou corretamente." Evite mensagens genéricas como "Inválido". Se o CPF tiver dígitos verificadores corretos mas não constar na base, permita que o usuário prossiga após confirmar os dados — casos de CPFs recém-emitidos ou situações especiais podem ocorrer.

### Leia também

- [Como pedir CPF no checkout sem espantar o cliente](https://cpfhub.io/blog/como-pedir-cpf-no-checkout-sem-espantar-o-cliente)
- [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma)
- [Como evitar chargebacks usando validação de CPF no checkout](https://cpfhub.io/blog/como-evitar-chargebacks-usando-validacao-de-cpf-no-checkout)
- [Como validar CPF no frontend com React e API REST](https://cpfhub.io/blog/como-validar-cpf-no-frontend-com-react-e-api-rest)

---

## Conclusão

Tooltips e mensagens de ajuda contextuais transformam o campo de CPF de uma fonte de atrito em uma experiência fluida e confiável. Ao combinar orientação clara com **validação em tempo real via API**, é possível reduzir erros de preenchimento, aumentar a confiança do usuário e melhorar significativamente as taxas de conversão.

A [**CPFHub.io**](https://www.cpfhub.io/) fornece a resposta estruturada necessária para compor mensagens de sucesso personalizadas, incluindo o nome do titular diretamente no feedback visual do formulário. Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente validação de CPF com feedback contextual nos seus formulários.