Spinner
Indica que um processo está em andamento ou que um conteúdo está carregando, por meio de um ícone animado sem texto.
- Indicar o processamento de uma tarefa sem avanço mensurável: comunicar que uma ação está em andamento quando não há nenhuma porcentagem ou valor de progresso real para mostrar. Ex.: salvar uma alteração, excluir um item ou carregar os resultados de uma busca.
- Substituir o conteúdo de um controle enquanto executa uma ação: trocar o ícone ou o texto de um botão enquanto dura a ação que ele dispara, para evitar que a pessoa clique novamente. Ex.: o botão "Salvar" enquanto persiste as alterações de um formulário.
- Sinalizar o carregamento de uma seção delimitada: mostrar que o conteúdo de uma card, um campo ou um arquivo anexado ainda está sendo obtido, quando esse conteúdo não tem uma estrutura previsível para antecipar. Ex.: o carregamento de uma imagem recém-enviada.
- Mostrar o avanço mensurável de uma tarefa: quando existe uma porcentagem ou um valor de progresso real para comunicar. Usar Progress Bar em vez disso. Ex.: a barra de upload de um arquivo com sua porcentagem concluída.
- Antecipar o carregamento de uma estrutura conhecida: representar de antemão a forma do conteúdo que vai aparecer, em vez de um ícone genérico sem relação com essa estrutura. Usar Skeleton em vez disso. Ex.: o carregamento de uma lista ou uma tabela completa.
- Comunicar o resultado final de uma operação: um sucesso, um erro ou um alerta posterior ao processo. Usar Toast em vez disso.
Icon
Small (16 px): usar dentro de controles compactos, como um botão, onde o Spinner substitui outro elemento pequeno. Ex.: o ícone de um botão enquanto executa a ação.
Medium (24 px): usar para indicar o carregamento de uma seção delimitada, como uma card ou um campo. Ex.: o carregamento de uma imagem recém-enviada.
Large (32 px, valor padrão): usar para indicar o carregamento de uma área principal, como o conteúdo principal de uma página ou de um modal. Ex.: o carregamento inicial de uma listagem.
currentColor: herda a cor do texto ou do ícone do elemento que contém o Spinner; usar quando ele substitui o conteúdo de um controle, para não quebrar sua paleta. Ex.: o ícone de um botão enquanto executa a ação.
primary-interactive (valor padrão): usar na maioria dos contextos, quando o Spinner aparece isolado sobre um fundo neutro. Ex.: o carregamento inicial de uma card ou de uma seção.
neutral-background: usar quando o Spinner está sobre um fundo de cor sólida, para que se distinga com contraste suficiente. Ex.: o Spinner dentro de um botão com aparência primary enquanto salva uma alteração.
danger-interactive: usar quando o processo está associado a uma ação destrutiva ou de risco. Ex.: o Spinner que substitui o ícone de um botão "Excluir" enquanto ele é executado.
success-interactive: usar quando o processo está associado a um contexto positivo ou de confirmação. Ex.: o Spinner dentro de uma ação de aprovação enquanto é confirmada.
O Spinner acompanha processos breves que não exigem antecipar uma estrutura: dentro de um botão, substituindo seu ícone ou seu texto enquanto a ação é executada; centralizado dentro de uma card, um campo ou um modal, enquanto seu conteúdo é obtido; ou isolado na área principal de uma página, durante um carregamento inicial breve.
Editar categoria
Substituir o conteúdo do botão pelo Spinner com color="currentColor" enquanto a ação está em andamento, e desabilitar a interação.
Evitar mostrar o Spinner junto ao texto do botão sem substituí-lo: duplica o sinal de carregamento e desalinha o conteúdo.
Excluindo cliente…
Usar o Spinner dentro de um Toast type="progress" para indicar que um processo continua em andamento, sem resultado de sucesso ou erro ainda.
Evitar usar o Spinner para representar o carregamento de uma lista ou uma tabela completa: em vez disso, antecipar sua estrutura com Skeleton.
- Rótulo acessível a cargo de quem implementa: o componente não inclui um aria-label por padrão; como não tem texto próprio, é preciso adicionar role="img" e aria-label diretamente no SVG do Spinner (Ex.: aria-label="Carregando"), ou fornecer texto descritivo dentro de uma região role="status".
- Não depende do foco nem do teclado: o Spinner é puramente informativo e não é interativo; não recebe foco nem trata eventos de teclado. Quando acompanha um controle, como um botão, o estado de foco e de interação é tratado por esse controle, não pelo Spinner.
- Contraste suficiente em relação ao fundo: escolher um valor de color que se distinga com clareza do fundo onde está posicionado. Ex.: neutral-background para um Spinner sobre uma superfície de cor sólida (primary-interactive, danger-interactive), ou currentColor para herdar a cor do elemento que ele substitui.
O Spinner não tem texto visível: seu único texto é o aria-label, que descreve o processo em andamento para tecnologias assistivas.
- Texto acessível explícito, sempre: o componente não tem texto visível próprio. Adicionar role="img" com um aria-label descritivo no SVG, ou um texto descritivo dentro de uma região role="status". Sem um dos dois, ele é inacessível.
- Verbo no gerúndio com objeto: ao usar aria-label, descrever a ação em andamento com seu contexto, sempre com objeto quando possível. "Carregando produtos", e não "Carregando".
- Conciso: uma ou duas palavras com objeto já bastam.
- Um só spinner por grupo de processos relacionados: se várias tarefas relacionadas correm em paralelo, mostrar um único spinner que represente o grupo. Áreas de carregamento independentes e não relacionadas (por exemplo, cards separados) podem ter cada uma seu próprio spinner.
- Quando mostrar: só se a espera passar de 1 segundo. Para esperas mais curtas, a mudança de estado já é suficiente.
| Caso | O que fazer |
|---|---|
Sem `aria-label` no SVG nem texto dentro de uma região `role="status"` | Adicionar um dos dois: sem nenhum, o Spinner não existe para leitores de tela. |
`aria-label` sem objeto ("Carregando") | Adicionar o objeto: "Carregando produtos", "Carregando pedidos". |
`aria-label` muito longo ("Estamos processando sua solicitação, aguarde") | Encurtar para verbo + objeto: "Processando solicitação". |
Vários spinners na tela com o mesmo `aria-label` | Adicionar contexto para diferenciá-los: "Carregando produtos" / "Carregando pedidos". |
Instale o componente via terminal.
npm install @nimbus-ds/spinnerimport React from "react";
import { Spinner } from "@nimbus-ds/components";
const Example: React.FC = () => <Spinner size="large" />;
export default Example;As propriedades adicionais são passadas ao elemento <Spinner>. Consulte a documentação do elemento SVG para ver a lista de atributos aceitos.
- Skeleton — Para antecipar a estrutura de um conteúdo conhecido enquanto carrega, em vez de um ícone genérico.
- Progress Bar — Para mostrar o avanço mensurável de uma tarefa, quando existe uma porcentagem real para comunicar.
- Toast — Para comunicar o resultado final de uma operação, uma vez que o processo tenha terminado.
Spinner
| Name | Type | Default | Description |
|---|---|---|---|
size | 'large' | 'large' | Sets the width and height of the spinner. |
color | 'currentColor' | 'primary-interactive' | Set the color for the spinner SVG fill. |
Ajude-nos a melhorar a documentação
Encontrou um problema ou tem uma sugestão? Conte para a gente.