# Como implementar skeleton loading durante consultas de CPF via API
> Aprenda a implementar skeleton loading enquanto sua aplicação consulta CPFs via API. Melhore a percepção de velocidade e reduza o abandono.
**Publicado:** 24/10/2024
**Autor:** Redação CPFHub.io
**URL:** https://cpfhub.io/blog/como-implementar-skeleton-loading-durante-consultas-de-cpf-via-api
---
Skeleton loading é a técnica de exibir blocos cinzas animados no lugar dos dados enquanto a API responde — e é especialmente eficaz para consultas de CPF, que levam ~900ms para retornar. Em vez de um spinner genérico, o usuário vê a estrutura exata do resultado (CPF, nome, gênero, nascimento), o que reduz a percepção de espera e diminui o abandono do fluxo de cadastro.
## Introdução
Quando sua aplicação consulta um CPF via API, existe um intervalo entre o envio da requisição e a chegada da resposta. Durante esse tempo, o usuário pode ficar olhando para uma tela em branco ou um spinner genérico, sem saber o que está acontecendo. O skeleton loading resolve esse problema ao exibir uma representação visual do conteúdo que será carregado, dando ao usuário a percepção de que o sistema está trabalhando de forma eficiente.
Essa técnica é especialmente útil quando integrada com APIs como a [**CPFHub.io**](https://www.cpfhub.io/), cujo tempo de resposta médio gira em torno de 900ms — tempo suficiente para o skeleton ser percebido, curto o bastante para não frustrar.
---
## O que é skeleton loading e por que usá-lo
Skeleton loading (ou skeleton screen) é uma técnica de UX em que, durante o carregamento de dados, a interface exibe blocos cinzas animados que simulam o formato do conteúdo final. Em vez de um spinner circular ou uma tela vazia, o usuário vê uma prévia da estrutura da informação.
### Vantagens sobre outros indicadores de carregamento
* **Percepção de velocidade** -- Estudos mostram que skeleton screens fazem o carregamento parecer até 30% mais rápido em comparação com spinners.
* **Contexto visual** -- O usuário entende qual tipo de informação será exibida, reduzindo a ansiedade.
* **Redução de abandono** -- A sensação de progresso mantém o usuário engajado durante a espera.
* **Transição suave** -- Quando os dados chegam, eles substituem o skeleton sem saltos bruscos na interface.
Para consultas de CPF, onde o tempo de resposta da API gira em torno de 900ms, o skeleton loading é particularmente eficaz: tempo suficiente para ser percebido, curto o bastante para não frustrar.
---
## Anatomia de um skeleton para dados de CPF
Ao projetar o skeleton, ele deve refletir a estrutura exata dos dados que serão exibidos. Uma consulta de CPF via API retorna campos como nome, CPF, gênero e data de nascimento. O skeleton deve ter placeholders para cada um desses campos.
### Estrutura sugerida
```
+------------------------------------------+
| [=======] (label: CPF) |
| [==================] (label: Nome) |
| [=====] (label: Gênero) |
| [==========] (label: Nascimento) |
+------------------------------------------+
```
Cada bloco `[===]` representa uma barra cinza animada com a largura aproximada do conteúdo final. Barras mais curtas para campos como gênero, mais longas para o nome completo.
---
## Implementação do skeleton em CSS
O componente de skeleton é simples de implementar com CSS puro. A animação de "shimmer" (brilho deslizante) é o padrão mais utilizado. Para referência sobre a propriedade `animation` e `@keyframes`, consulte o [MDN Web Docs](https://developer.mozilla.org/pt-BR/docs/Web/CSS/animation):
```css
.skeleton {
background: linear-gradient(
90deg,
#e0e0e0 25%,
#f0f0f0 50%,
#e0e0e0 75%
);
background-size: 200% 100%;
animation: shimmer 1.5s infinite;
border-radius: 4px;
height: 20px;
margin-bottom: 12px;
}
.skeleton--nome {
width: 70%;
}
.skeleton--cpf {
width: 40%;
}
.skeleton--genero {
width: 25%;
}
.skeleton--nascimento {
width: 35%;
}
@keyframes shimmer {
0% {
background-position: 200% 0;
}
100% {
background-position: -200% 0;
}
}
```
Esse CSS cria barras de diferentes larguras com uma animação de brilho contínuo que comunica ao usuário que os dados estão sendo carregados.
---
## Componente React com skeleton loading e consulta à API
Veja um componente completo que integra skeleton loading com a consulta de CPF via [**CPFHub.io**](https://www.cpfhub.io/), mostrando o skeleton imediatamente ao clicar em "Consultar" e substituindo-o pelos dados reais quando a resposta chega:
```javascript
import { useState } from 'react';
function ConsultaCPF() {
const [cpf, setCpf] = useState('');
const [dados, setDados] = useState(null);
const [carregando, setCarregando] = useState(false);
const [erro, setErro] = useState('');
const consultar = async () => {
const cpfLimpo = cpf.replace(/\D/g, '');
if (cpfLimpo.length !== 11) {
setErro('O CPF precisa ter 11 dígitos.');
return;
}
setCarregando(true);
setErro('');
setDados(null);
try {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 10000);
const response = await fetch(
`https://api.cpfhub.io/cpf/${cpfLimpo}`,
{
headers: {
'x-api-key': 'SUA_CHAVE_DE_API',
'Accept': 'application/json'
},
signal: controller.signal
}
);
clearTimeout(timeout);
const resultado = await response.json();
if (resultado.success) {
setDados(resultado.data);
} else {
setErro('CPF não encontrado. Verifique o número informado.');
}
} catch (e) {
setErro('Erro na consulta. Tente novamente.');
} finally {
setCarregando(false);
}
};
return (
);
}
```
Nesse exemplo, o skeleton é exibido imediatamente quando o botão de consulta é clicado e desaparece quando os dados reais chegam da API, criando uma transição natural.
---
## Boas práticas para skeleton loading em consultas de CPF
### Mantenha o skeleton fiel ao resultado
O skeleton deve ter a mesma estrutura e posição que os dados reais. Se o nome aparece acima do gênero no resultado final, o skeleton deve seguir a mesma ordem. Isso evita que o conteúdo "salte" quando os dados substituem o skeleton.
### Não exiba skeleton por tempo fixo
Um erro comum é forçar o skeleton a aparecer por um tempo mínimo (ex: 2 segundos), independentemente da velocidade da API. Se a resposta chegar em 500ms, mostre os dados imediatamente. Artificialmente prolongar o carregamento prejudica a experiência.
### Combine com validação local
Antes de exibir o skeleton e chamar a API, valide o formato do CPF localmente. Isso evita que o usuário veja o skeleton para uma requisição que falharia imediatamente por CPF inválido.
### Adicione acessibilidade
Use atributos ARIA para comunicar o estado de carregamento a leitores de tela:
```html
```
---
## Quando não usar skeleton loading
Existem situações em que o skeleton pode não ser a melhor escolha:
* **Validações instantâneas** -- Se a validação é apenas sintática (local), não há necessidade de skeleton. O resultado é imediato.
* **Ações em segundo plano** -- Se a consulta de CPF acontece em background sem que o usuário precise ver o resultado na hora, um skeleton é desnecessário.
* **Telas de listagem com muitos itens** -- Para consultas em massa, um indicador de progresso com porcentagem pode ser mais informativo que múltiplos skeletons.
---
## Perguntas frequentes
### Por que usar skeleton loading em vez de spinner para consultas de CPF?
Spinners comunicam apenas "algo está acontecendo", sem contexto. O skeleton mostra exatamente quais dados serão exibidos (CPF, nome, nascimento, gênero), reduzindo a ansiedade do usuário e tornando os ~900ms de latência da API subjetivamente mais curtos. Pesquisas de UX indicam que skeleton screens são percebidos como até 30% mais rápidos que spinners equivalentes.
### Como evitar o "salto" de layout quando os dados reais substituem o skeleton?
Defina alturas e larguras fixas para os blocos skeleton que correspondam às dimensões reais dos dados. Use `min-height` nos containers de resultado para que o layout não mude quando o conteúdo chegar. Aplicar `transition: opacity 0.2s` na troca do skeleton pelos dados também suaviza a transição visualmente.
### A API CPFHub.io pode demorar mais que 900ms em alguns casos?
Sim, variações de rede podem aumentar a latência ocasionalmente. Por isso, configure sempre um timeout de 10 segundos no `fetch` ou `axios`. O skeleton deve continuar visível durante todo esse intervalo. Se o timeout for atingido, exiba uma mensagem de erro clara com opção de tentar novamente — sem esconder o skeleton abruptamente.
### A API CPFHub.io bloqueia requisições por rate limit durante picos de uso?
Não. A CPFHub.io nunca retorna HTTP 429 nem bloqueia o acesso, mesmo em picos. Ao ultrapassar o limite do plano gratuito (50 consultas/mês), as consultas adicionais são cobradas a R$0,15 cada. Isso garante que o skeleton loading nunca seja exibido por causa de um bloqueio inesperado da API.
### Leia também
- [Skeleton loading vs. spinner na consulta de CPF: qual converte mais](https://cpfhub.io/blog/skeleton-loading-vs-spinner-consulta-cpf-qual-converte-mais)
- [Como usar skeleton screens durante a validação de CPF para melhorar a percepção de velocidade](https://cpfhub.io/blog/como-usar-skeleton-screens-durante-a-validacao-de-cpf)
- [Como agilizar o preenchimento de formulários usando APIs de validação de CPF](https://cpfhub.io/blog/como-agilizar-preenchimento-de-formularios-com-apis-de-cpf)
- [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
Skeleton loading é uma técnica simples e eficaz para melhorar a experiência do usuário durante consultas de CPF via API. Ao exibir uma representação visual da estrutura dos dados enquanto a resposta é processada, você reduz a percepção de espera e mantém o usuário engajado no fluxo.
Cadastre-se em [cpfhub.io](https://www.cpfhub.io/) — 50 consultas mensais gratuitas, sem cartão de crédito — e implemente a consulta de CPF com skeleton loading no seu próximo projeto.