SVG Progress Ring

Progress rings em SVG: indicadores circulares para progresso determinado

Um progress ring (também chamado de circular progress, barra radial ou donut progress) é o primo circular da barra de progresso linear. Em vez de preencher um retângulo da esquerda para a direita, ele preenche o perímetro de um círculo no sentido horário a partir do topo. É o padrão certo quando o progresso é determinado — você sabe a porcentagem — e a UI ao redor se beneficia de uma forma compacta tipo badge: widgets de upload, KPIs de dashboard, players de música, anéis de atividade do Apple Watch. A implementação em SVG é um único <circle> cujo stroke-dasharray é igual à circunferência completa e cujo stroke-dashoffset esconde a porção não preenchida.

A matemática: circunferência, dasharray, dashoffset

Para raio r, a circunferência é C = 2 * π * r. Com r = 45 a circunferência é ≈ 282.74. Defina stroke-dasharray igual a essa circunferência (para o padrão de traços durar todo o perímetro) e anime stroke-dashoffset de C (vazio) até 0 (cheio). O offset para qualquer porcentagem é C * (1 - percent / 100). Aplique transform: rotate(-90deg) para que o preenchimento comece em doze horas em vez de três:

const circle = document.querySelector('.progress');
const C = 2 * Math.PI * 45;
circle.style.strokeDasharray = C;
circle.style.strokeDashoffset = C * (1 - percent / 100);

Suavização, gradientes e label central

Um anel puro pula bruscamente quando o percentual atualiza. Adicione transition: stroke-dashoffset 0.5s ease-out no traço e o navegador interpola entre valores de graça. Para a cor, a primária da marca funciona para "em progresso", mas uma paleta semântica ajuda: verde para sucesso / acima da meta, amarelo para alerta, vermelho para limite ultrapassado. Traços com gradiente são suportados via stroke="url(#gradient)" referenciando um <linearGradient> em <defs>. Para o label de porcentagem no centro, use um <text x="50" y="50" text-anchor="middle" dominant-baseline="central"> filho ou HTML posicionado em absolute sobre o SVG (HTML vence se você precisa de tipografia rica ou ícones).

Casos de uso e inspirações

• Upload de arquivo — porcentagem preenchida conforme os bytes transferem (Google Drive, Dropbox).
• KPI de dashboard — "meta atingida 73%" em ferramentas de analytics como Mixpanel ou Amplitude.
• Player de música — tempo decorrido da faixa, YouTube e Spotify ambos usam progresso radial no miniplayer.
• Conquistas — XP até o próximo nível, metas diárias do Duolingo, distância mensal do Strava.
• Apple HealthKit rings — três anéis concêntricos sobrepostos para mover, exercitar e ficar em pé, design icônico desde o watchOS 1.

Acessibilidade, SVG vs Canvas, bibliotecas

Exponha role="progressbar", aria-valuenow, aria-valuemin="0" e aria-valuemax="100" na raiz do SVG. Leitores de tela anunciam "65 por cento carregado". SVG é mais acessível que Canvas (cada nó é elemento DOM e estilizável individualmente) e escala sem rasterização; Canvas só vence quando você precisa desenhar milhares de anéis simultaneamente. Para soluções prontas tente ProgressBar.js de Kimmo Brunfeldt, react-progressbar.js, ou vue-circular-progress.

Perguntas frequentes

E se a porcentagem passar de 100? Um pequeno overshoot lê visualmente como "meta excedida" — limite em 100 só se o design tratar acima da meta como apenas "feito". Os activity rings da Apple ultrapassam de propósito e começam uma segunda volta.

SVG ou Canvas? SVG para um ou poucos anéis (acessível, escalável, estilizável via CSS). Canvas só quando você tem centenas ou milhares de indicadores em uma única view.

Como mostrar vários anéis empilhados? Elementos <circle> concêntricos com raios decrescentes e cores diferentes, cada um com seu próprio dashoffset. O activity ring da Apple usa exatamente essa abordagem.

Posso animar o preenchimento? Sim — anime stroke-dashoffset com transition CSS ou Web Animations API. Evite animar o raio em si, que dispara reflow.