NovoVerificação de identidade facial

Skeleton loading vs. spinner na consulta de CPF: qual converte mais

Compare skeleton loading e spinner na consulta de CPF. Descubra qual padrão de loading reduz abandono e melhora a percepção de velocidade.

Lucas Vieira
Lucas Vieira
··9 min de leitura
Skeleton loading vs. spinner na consulta de CPF: qual converte mais

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étricaSpinnerSkeleton
Tempo percebido~1.2s~0.8s
Taxa de re-clique4-6%1-2%
Satisfação (NPS)7.28.1
Layout shiftSimNã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.

WhatsApp