Spinner
Indicadores de carregamento animados com tamanhos de controle e estilos default/on-color.Animated loading indicators with control sizes and default/on-color styles.
Quando usarWhen to use
Use spinners quandoUse spinners when
Indicando carregamento indeterminado: dentro de buttons durante ações assincronas, inline em áreas de conteúdo, ou centralizado para estados de carregamento de página inteira.Indicating indeterminate loading: inside buttons during async actions, inline in content areas, or centered for full-page loading states.
Não use spinners quandoDon't use spinners when
A estrutura do conteúdo e conhecida antecipadamente (use Skeleton) ou a espera e muito curta — mostrar um spinner para operações breves causa desconforto.The content structure is known ahead of time (use Skeleton instead) or the wait is very short -- showing a spinner for brief operations feels jarring.
AnatomiaAnatomy
1 Container (
2 Ring — borda circular animada por rotação linear.
3 Size/style modifiers —
2 Ring — circular border animated with linear rotation.
3 Size/style modifiers —
.ds-spinner) — elemento inline flex com tamanho tokenizado.2 Ring — borda circular animada por rotação linear.
3 Size/style modifiers —
--sm, --md, --lg e --on-color.
1 Container (.ds-spinner) — inline-flex element with tokenized size.2 Ring — circular border animated with linear rotation.
3 Size/style modifiers —
--sm, --md, --lg, and --on-color.
TamanhosSizes
Três tamanhos para diferentes contextos: sm, md e lg.Three sizes to suit different contexts: sm, md, and lg.
sm
md
lg
EstilosStyles
Use default sobre superfícies neutras e on-color sobre fundos coloridos ou invertidos.Use default on neutral surfaces and on-color on colored or inverted backgrounds.
Estado de carregamento no buttonButton loading state
Spinners dentro de buttons indicam que uma ação está em andamento. O button não e interativo enquanto carrega.Spinners inside buttons indicate that an action is in progress. The button is non-interactive while loading.
Carregamento centralizadoCentered loading
Use um spinner grande centralizado em um container para estados de carregamento de área completa.Use a large spinner centered in a container for full-area loading states.
Loading content...
Boas práticasBest practices
Show after short delay
Faça
Mostre o spinner após um atraso curto para evitar um flash em operações rapidas.Show the spinner after a short delay to avoid a flash for fast operations.
Não faça
Não substitua uma página inteira por apenas um spinner — use Skeleton placeholders para previsualizar a estrutura do layout.Don't replace an entire page with just a spinner -- use Skeleton placeholders to preview the layout structure.
Mapeamento de tokensToken mapping
| PropriedadeProperty | Token | Variável CSSCSS variable |
|---|---|---|
| root size (sm/md/lg) | component.spinner.size.sm/md/lg | --ds-spinner-root-size-* (16/24/32px) |
| root radius | component.spinner.radius.default | --ds-spinner-radius-default |
| espessurastroke width | component.spinner.ring.stroke-width.default | --ds-spinner-ring-stroke-width-default (2px) |
| indicador defaultdefault indicator | semantic.border.brand | --ds-border-brand |
| trilha defaultdefault track | semantic.border.subtle | --ds-border-subtle |
| indicador on-coloron-color indicator | semantic.border.inverse | --ds-border-inverse |
| trilha on-coloron-color track | semantic.overlay.medium | --ds-overlay-medium |
| duração da animaçãoanimation duration | semantic.motion.duration.slower | --ds-motion-duration-slower |
| curva da animaçãoanimation easing | semantic.motion.ease.linear | --ds-motion-ease-linear |
Classes CSSCSS classes
| ClasseClass | DescriçãoDescription |
|---|---|
ds-spinner | Classe base do spinnerBase spinner class |
ds-spinner--sm | Tamanho pequeno (16px)Small size (16px) |
ds-spinner--md | Tamanho médio (24px) — também é o padrão da classe baseMedium size (24px) — also the default on the base class |
ds-spinner--lg | Tamanho grande (32px)Large size (32px) |
ds-spinner--on-color | Estilo para fundos coloridos ou invertidosStyle for colored or inverted backgrounds |
AccessibilityAccessibility
| Critério WCAGWCAG criterion | RequisitoRequirement | Status |
|---|---|---|
| 4.1.2 Name, Role, Value (A) | role="status" + aria-label="Loading" em cada spinnerrole="status" + aria-label="Loading" on every spinner | ✓ |
| 2.3.1 Three Flashes (A) | A animação e uma rotacao continua, não piscanteAnimation is a continuous rotation, not flashing | ✓ |
| 2.3.3 Animation from Interactions (AAA) | Respeita prefers-reduced-motion — animação pausada ou desaceleradaRespects prefers-reduced-motion -- animation paused or slowed | ✓ |
Resumo dos atributos ARIAARIA attributes summary
role="status" + aria-label="Loading" — obrigatorio em cada spinner para que leitores de tela anunciem o estado de carregamento.aria-busy="true" — defina no container quando o spinner substitui conteúdo.prefers-reduced-motion — o CSS do spinner respeita esta media query pausando ou reduzindo a animação.role="status" + aria-label="Loading" — required on every spinner so screen readers announce the loading state.aria-busy="true" — set on the container when the spinner replaces content.prefers-reduced-motion — the spinner CSS respects this media query by pausing or reducing animation.