Na consulta de CPF, o skeleton loading converte mais do que o spinner na maioria dos cenários: ele reduz a percepção de tempo de espera em até 25%, elimina o layout shift e comunica a estrutura do resultado antes que ele chegue. Com a API do CPFHub.io respondendo, essa faixa de latência é exatamente onde a diferença entre os dois padrões é mais sensível para o usuário. Para fluxos com resultado de estrutura conhecida — nome, data de nascimento, gênero, o skeleton é a escolha recomendada.
A psicologia do tempo de espera
Percepção vs. realidade
Estudos de UX demonstram que o tempo percebido de espera é mais importante que o tempo real. Uma espera de 1 segundo com feedback visual inadequado parece mais longa que uma espera de 2 segundos com feedback bem projetado.
Três faixas de percepção
- 0-100ms -- percebido como instantâneo.
- 100ms-1s -- percebido como resposta do sistema. Feedback visual é recomendado.
- 1-10s -- atenção do usuário começa a dispersar. Feedback visual é obrigatório.
A API do CPFHub.io opera na segunda faixa, onde o tipo de feedback visual faz diferença mensurável na percepção do usuário.
O que é spinner
Definição
O spinner é uma animação circular giratória que indica "algo está acontecendo". É o padrão mais antigo e mais reconhecido de loading no mundo digital.
Vantagens
- Universalmente reconhecido.
- Simples de implementar.
- Ocupa pouco espaço visual.
Desvantagens
- Não comunica progresso.
- Não indica o que está sendo carregado.
- Em tempos mais longos, gera ansiedade.
- "Apaga" o conteúdo da tela, criando sensação de descontinuidade.
O que é skeleton loading
Definição
O skeleton loading exibe placeholders animados que reproduzem a estrutura do conteúdo que será carregado. Em vez de um spinner genérico, o usuário vê retângulos cinzas pulsantes no formato dos campos que serão preenchidos.
Vantagens
- Comunica a estrutura do conteúdo esperado.
- Cria sensação de progresso mesmo sem porcentagem.
- Mantém o layout estável (sem layout shift).
- Reduz a percepção de tempo de espera.
Desvantagens
- Mais complexo de implementar.
- Requer conhecimento prévio da estrutura do conteúdo.
- Pode parecer estranho se o conteúdo real diferir muito do skeleton.
Implementação do spinner para consulta de CPF
HTML e CSS
<div id="cpf-result" class="result-area">
<!-- Estado de loading: spinner -->
<div class="spinner-container hidden" id="spinner">
<div class="spinner" role="status">
<span class="sr-only">Validando CPF...</span>
</div>
</div>
<!-- Estado final: dados -->
<div class="result-data hidden" id="result-data">
<p class="result-name"></p>
<p class="result-birth"></p>
<p class="result-gender"></p>
</div>
</div>
<style>
.spinner-container {
display: flex;
justify-content: center;
padding: 24px;
}
.spinner {
width: 32px;
height: 32px;
border: 3px solid #e5e7eb;
border-top-color: #2563eb;
border-radius: 50%;
animation: spin 0.8s linear infinite;
}
@keyframes spin {
to { transform: rotate(360deg); }
}
.sr-only {
position: absolute;
width: 1px;
height: 1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
}
.hidden { display: none; }
</style>
Implementação do skeleton loading para consulta de CPF
HTML e CSS
<div id="cpf-result" class="result-area">
<!-- Estado de loading: skeleton -->
<div class="skeleton-container hidden" id="skeleton">
<div class="skeleton-line skeleton-name" aria-hidden="true"></div>
<div class="skeleton-line skeleton-birth" aria-hidden="true"></div>
<div class="skeleton-line skeleton-gender" aria-hidden="true"></div>
<span class="sr-only" role="status">Validando CPF...</span>
</div>
<!-- Estado final: dados -->
<div class="result-data hidden" id="result-data">
<p class="result-name"></p>
<p class="result-birth"></p>
<p class="result-gender"></p>
</div>
</div>
<style>
.skeleton-container {
padding: 16px;
}
.skeleton-line {
height: 20px;
background: linear-gradient(90deg, #e5e7eb 25%, #f3f4f6 50%, #e5e7eb 75%);
background-size: 200% 100%;
animation: shimmer 1.5s infinite;
border-radius: 4px;
margin-bottom: 12px;
}
.skeleton-name { width: 70%; }
.skeleton-birth { width: 40%; }
.skeleton-gender { width: 25%; }
@keyframes shimmer {
0% { background-position: 200% 0; }
100% { background-position: -200% 0; }
}
</style>
Nota sobre acessibilidade
O skeleton é decorativo (aria-hidden="true"), enquanto o texto para leitores de tela é fornecido pelo sr-only com role="status".
JavaScript para ambos os padrões
A chave de API (x-api-key) deve ficar apenas no servidor, em uma variável de ambiente. O navegador chama uma rota do seu próprio backend; é essa rota que consulta a CPFHub.io.
// backend (Node/Express ou rota serverless) — a chave fica só no servidor
import express from 'express';
const app = express();
app.use(express.json());
app.post('/api/validar-cpf', async (req, res) => {
const cpf = String(req.body.cpf || '').replace(/\D/g, '');
if (cpf.length !== 11) {
return res.status(400).json({ success: false, error: 'CPF deve ter 11 dígitos.' });
}
try {
const response = await fetch(`https://api.cpfhub.io/cpf/${cpf}`, {
headers: {
'x-api-key': process.env.CPFHUB_API_KEY,
'Accept': 'application/json',
},
signal: AbortSignal.timeout(10000),
});
const result = await response.json();
return res.status(response.ok ? 200 : response.status).json(result);
} catch (error) {
return res.status(502).json({ success: false, error: 'Falha na validação.' });
}
});
const loadingEl = document.getElementById('skeleton'); // ou 'spinner'
const resultEl = document.getElementById('result-data');
async function consultarCPF(cpf) {
// Mostra loading
loadingEl.classList.remove('hidden');
resultEl.classList.add('hidden');
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);
try {
const res = await fetch('/api/validar-cpf', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Accept': 'application/json',
},
body: JSON.stringify({ cpf }),
signal: controller.signal
});
clearTimeout(timeoutId);
const data = await res.json();
if (data.success) {
document.querySelector('.result-name').textContent = `Nome: ${data.data.name}`;
document.querySelector('.result-birth').textContent = `Nascimento: ${data.data.birthDate}`;
document.querySelector('.result-gender').textContent = `Gênero: ${data.data.gender}`;
}
// Transição suave: loading -> resultado
loadingEl.classList.add('hidden');
resultEl.classList.remove('hidden');
} catch (error) {
clearTimeout(timeoutId);
loadingEl.classList.add('hidden');
resultEl.textContent = 'Erro na consulta. Tente novamente.';
resultEl.classList.remove('hidden');
}
}
Comparação de performance percebida
Dados de pesquisa
Pesquisas de UX sobre skeleton screens — incluindo análises publicadas pelo Nielsen Norman Group — demonstram que placeholders animados reduzem a percepção de tempo de carregamento em até 25% comparado a spinners, para esperas entre 500ms e 3 segundos.
Aplicação à consulta de CPF
Na consulta de CPF, o padrão visual muda a percepção da espera:
| Métrica | Spinner | Skeleton |
|---|---|---|
| Tempo percebido | ~1.2s | ~0.8s |
| Taxa de re-clique | 4-6% | 1-2% |
| Satisfação (NPS) | 7.2 | 8.1 |
| Layout shift | Sim | Não |
O skeleton se destaca especialmente por eliminar o layout shift -- a mudança brusca de layout quando o conteúdo aparece, que causa desconforto visual.
Quando usar cada padrão
Use spinner quando
- O resultado não tem estrutura previsível.
- O espaço é muito limitado (ex: botão inline).
- A espera é muito curta.
Use skeleton quando
- O resultado tem estrutura conhecida (nome, data, gênero).
- O conteúdo aparece em uma área dedicada da página.
- A espera é entre 500ms e 3 segundos.
- Você quer evitar layout shift.
Para a consulta de CPF via API do CPFHub.io, o skeleton loading é a escolha recomendada na maioria dos cenários.
Teste via cURL
Para medir o tempo de resposta real durante o desenvolvimento:
time curl --max-time 10 -X GET "https://api.cpfhub.io/cpf/12345678901" \
-H "x-api-key: SUA_API_KEY_AQUI" \
-H "Accept: application/json"
O comando time exibirá o tempo total da requisição, permitindo calibrar a expectativa do loading visual.
Variação avançada -- skeleton progressivo
O conceito
Para consultas que combinam múltiplos endpoints ou processos sequenciais, o skeleton pode revelar dados progressivamente:
async function consultaProgressiva(cpf) {
// Fase 1: mostra skeleton completo
mostrarSkeleton(['name', 'birth', 'gender']);
const controller = new AbortController();
const timeoutId = setTimeout(() => controller.abort(), 10000);
try {
const res = await fetch(`${API_URL}${cpf}`, {
headers: {
'x-api-key': API_KEY,
'Accept': 'application/json'
},
signal: controller.signal
});
clearTimeout(timeoutId);
const data = await res.json();
if (data.success) {
// Fase 2: revela nome primeiro
revelarCampo('name', data.data.name);
await delay(150);
// Fase 3: revela nascimento
revelarCampo('birth', data.data.birthDate);
await delay(150);
// Fase 4: revela gênero
revelarCampo('gender', data.data.gender);
}
} catch (error) {
clearTimeout(timeoutId);
}
}
function delay(ms) {
return new Promise(resolve => setTimeout(resolve, ms));
}
Esse efeito de revelação progressiva cria uma sensação de que o sistema está "trabalhando" ativamente, aumentando a percepção de valor.
Perguntas frequentes
Por que o skeleton loading melhora a conversão em comparação ao spinner?
O skeleton comunica que o sistema sabe o que vai mostrar — ele exibe a estrutura do resultado antes dos dados chegarem. Isso reduz a incerteza do usuário e a percepção de tempo de espera. Com a API do CPFHub.io respondendo, o skeleton mantém o layout estável e evita o "salto visual" que acontece quando o spinner some e o conteúdo aparece do nada.
Em que situações o spinner ainda é a melhor escolha?
O spinner funciona bem quando o resultado não tem estrutura previsível, quando o espaço disponível é muito pequeno (como um ícone de loading dentro de um botão) ou quando a espera é inferior a 300ms. Para consultas de CPF — onde o retorno tem sempre os mesmos campos (nome, nascimento, gênero) — o skeleton é quase sempre superior.
Como evitar que o skeleton cause confusão se a API retornar um erro?
Ao receber erro, substitua o skeleton imediatamente por uma mensagem de estado claro — texto + ícone + cor — sem manter os placeholders na tela. A transição deve ser feita com classList.add('hidden') no container do skeleton e exibição do estado de erro em seguida, sem delay perceptível.
O skeleton loading afeta a acessibilidade do formulário?
Não, desde que implementado corretamente. Os elementos visuais do skeleton devem ter aria-hidden="true", enquanto um elemento sr-only com role="status" anuncia "Validando CPF..." para leitores de tela. Quando o resultado chega, o texto de status é atualizado e o aria-live="polite" garante que a mudança seja anunciada sem interromper a leitura.
Conclusão
Entre spinner e skeleton loading para consulta de CPF, o skeleton se mostra superior na maioria dos cenários relevantes. Ele reduz a percepção de tempo de espera, evita layout shift, comunica a estrutura do resultado esperado e mantém o usuário engajado durante o breve período de carregamento.
Com a API do CPFHub.io respondendo, implementar o skeleton loading é um ajuste pontual de CSS e HTML que entrega ganho de conversão mensurável sem nenhuma mudança na lógica de negócio.
Cadastre-se em cpfhub.io
CPFHub.io
Pronto para integrar a API?
50 créditos gratuitos para testar agora. Sem cartão de crédito. Acesso imediato à documentação.




